Chapter 2. A Tour of the Dart Language

Table 2.1, “Dart keywords” lists the words that the Dart language reserves.

We recommend that you develop and debug in checked mode, and deploy to production mode.

Production mode is the default runtime mode of a Dart program, optimized for speed. Production mode ignores assert statements and static types.

Checked mode is a developer-friendly mode that helps you catch some type errors during runtime. For example, if you assign a non-number to a variable declared as a num, then checked mode throws an exception.

Uninitialized variables have an initial value of null. Even variables with numeric types are initially null, because numbers are objects.

lang-dart
int lineCount;
assert(lineCount == null); 
// Variables (even if they will be numbers) are initially null.

You have the option of adding static types to your variable declarations:

lang-dart
String name = 'Bob';

Adding types is a way to clearly express your intent. Tools such as compilers and editors can use these types to help you, by providing early warnings for bugs and code completion.

If you never intend to change a variable, use final or const, either instead of var or in addition to a type. A final variable can be set only once; a const variable is a compile-time constant.

A local, top-level, or class variable that’s declared as final is initialized the first time it’s used:

lang-dart
final name = 'Bob';   // Or: final String name = 'Bob';
// name = 'Alice';    // Uncommenting this results in an error

Use const for variables that you want to be compile-time constants. Where you declare the variable, set the value to a compile-time constant such as a literal, a const variable, or the result of an arithmetic operation on constant numbers:

lang-dart
const bar = 1000000;       // Unit of pressure (in dynes/cm2)
const atm = 1.01325 * bar; // Standard atmosphere

Dart numbers come in two flavors:

Both int and double are subtypes of num. The num type includes basic operators such as +, -, /, and *, as well as bitwise operators such as >>. The num type is also where you’ll find abs(), ceil(), and floor(), among other methods. If num and its subtypes don’t have what you’re looking for, the Math library might. (In JavaScript produced from Dart code, big integers currently behave differently than they do when the same Dart code runs in the Dart VM.)

Integers are numbers without a decimal point. Here are some examples of defining integer literals:

lang-dart
var x = 1;
var hex = 0xDEADBEEF;
var bigInt = 346534658346524376592384765923749587398457294759347029438709349347;

If a number includes a decimal, it is a double. Here are some examples of defining double literals:

lang-dart
var y = 1.1;
var exponents = 1.42e5;

Here’s how you turn a string into a number, or vice versa:

lang-dart
// String -> int
var one = int.parse('1');
assert(one == 1);

// String -> double
var onePointOne = double.parse('1.1');
assert(onePointOne == 1.1);

// int -> String
String oneAsString = 1.toString();
assert(oneAsString == '1');

// double -> String
String piAsString = 3.14159.toStringAsFixed(2);
assert(piAsString == '3.14');

The int type specifies the traditional bitwise shift (<<, >>), AND (&), and OR (|) operators. For example:

lang-dart
assert((3 << 1) == 6);  // 0011 << 1 == 0110
assert((3 >> 1) == 1);  // 0011 >> 1 == 0001
assert((3 | 4)  == 7);  // 0011 | 0100 == 0111

A Dart string is a sequence of UTF-16 code units. You can use either single or double quotes to create a string:

lang-dart
var s1 = 'Single quotes work well for string literals.';
var s2 = "Double quotes work just as well.";
var s3 = 'It\'s easy to escape the string delimiter.';
var s4 = "It's even easier to just use the other string delimiter.";

You can put the value of an expression inside a string by using ${expression}. If the expression is an identifier, you can skip the {}. To get the string corresponding to an object, Dart calls the object’s toString() method.

lang-dart
var s = 'string interpolation';

assert('Dart has $s, which is very handy.' ==
       'Dart has string interpolation, which is very handy.');
assert('That deserves all caps. ${s.toUpperCase()} is very handy!' ==
       'That deserves all caps. STRING INTERPOLATION is very handy!');

You can concatenate strings using adjacent string literals:

lang-dart
var s = 'String ' 'concatenation'
        " works even over line breaks.";
assert(s == 'String concatenation works even over line breaks.');

Another way to create a multi-line string: use a triple quote with either single or double quotation marks:

lang-dart
var s1 = '''
You can create
multi-line strings like this one.
''';

var s2 = """This is also a
multi-line string.""";

You can create a “raw” string by prefixing it with r:

lang-dart
var s = r"In a raw string, even \n isn't special.";

You can use Unicode escapes inside of strings:

lang-dart
ch02/quoting.dart
print('Unicode escapes work: \u2665'); // Unicode escapes work: [heart]

For more information on using strings, see the section called “Strings and Regular Expressions”.

To represent boolean values, Dart has a type named bool. Only two objects have type bool: the boolean literals, true and false.

When Dart expects a boolean value, only the value true is treated as true. All other values are treated as false. Unlike in JavaScript, values such as 1, "aString", and someObject are all treated as false.

For example, consider the following code, which is valid both as JavaScript and as Dart code:

lang-dart
var name = 'Bob';
if (name) {
  print('You have a name!'); // Prints in JavaScript, not in Dart.
}

If you run this code as JavaScript, it prints “You have a name!” because name is a non-null object. However, in Dart running in production mode, the above doesn’t print at all because name is converted to false (because name != true). In Dart running in checked mode, the above code throws an exception because the name variable is not a bool.

Here’s another example of code that behaves differently in JavaScript and Dart:

lang-dart
if (1) {
  print('JavaScript prints this line because it thinks 1 is true.');
} else {
  print('Dart in production mode prints this line.');
  // However, in checked mode, if (1) throws an exception.
}

Dart’s treatment of booleans is designed to avoid the strange behaviors that can arise when many values can be treated as true. What this means for you is that, instead of using code like if (nonbooleanValue), you should instead explicitly check for values. For example:

lang-dart
// Check for an empty string.
var fullName = '';
assert(fullName.isEmpty);

// Check for zero.
var hitPoints = 0;
assert(hitPoints <= 0);

// Check for null.
var unicorn;
assert(unicorn == null);

// Check for NaN.
var iMeantToDoThis = 0/0;
assert(iMeantToDoThis.isNaN);

Perhaps the most common collection in nearly every programming language is the array, or ordered group of objects. In Dart, arrays are List objects, so we usually just call them lists.

Dart list literals look like JavaScript array literals. Here’s a simple Dart list:

lang-dart
var list = [1,2,3];

Lists use zero-based indexing, where 0 is the index of the first element and list.length - 1 is the index of the last element. You can get a list’s length and refer to list elements just as you would in JavaScript:

lang-dart
var list = [1,2,3];
assert(list.length == 3);
assert(list[1] == 2);

The List type has many handy methods for manipulating lists. For more information about lists, see the section called “Generics” and the section called “Collections”.

In general, a map is an object that associates keys and values. Dart support for maps is provided by map literals and the Map type.

Here’s a simple Dart map:

lang-dart
var gifts = {                         // A map literal
// Keys       Values
  'first'  : 'partridge',
  'second' : 'turtledoves',
  'fifth'  : 'golden rings'
};

In map literals, each key must be a string. If you use a Map constructor, any object can be a key.

lang-dart
ch02/map_constructor.dart
var map = new Map();                  // Use a map constructor.
map[1] = 'partridge';                 // Key is 1; value is 'partridge'.
map[2] = 'turtledoves';               // Key is 2; value is 'turtledoves'.
map[5] = 'golden rings';              // Key is 5; value is 'golden rings'.

A map value can be any object, including null.

You add a new key-value pair to an existing map just as you would in JavaScript:

lang-dart
var gifts = { 'first': 'partridge' };
gifts['fourth'] = 'calling birds';    // Add a key-value pair

You retrieve a value from a map the same way you would in JavaScript:

lang-dart
var gifts = { 'first': 'partridge' };
assert(gifts['first'] == 'partridge');

If you look for a key that isn’t in a map, you get a null in return:

lang-dart
var gifts = { 'first': 'partridge' };
assert(gifts['fifth'] == null);

Use .length to get the number of key-value pairs in the map:

lang-dart
var gifts = { 'first': 'partridge' };
gifts['fourth'] = 'calling birds';
assert(gifts.length == 2);

For more information about maps, see the section called “Generics” and the section called “Maps”.

Optional parameters can be either positional or named, but not both.

Both kinds of optional parameter can have default values. The default values must be compile-time constants such as literals. If no default value is provided, the value is null.

If you need to know whether the caller passed in a value for an optional parameter, use the syntax ?param:

lang-dart
if (?device) {    // Returns true if the caller specified the parameter.
  // ...The user set the value. Do something with it...
}

lang-dart
enableFlags(bold: true, hidden: false);

lang-dart
/// Sets the [bold] and [hidden] flags to the values you specify.
enableFlags({bool bold, bool hidden}) {
  // ...
}

lang-dart
/**
 * Sets the [bold] and [hidden] flags to the values you specify,
 * defaulting to false.
 */
enableFlags({bool bold: false, bool hidden: false}) {
  // ...
}

enableFlags(bold: true); // bold will be true; hidden will be false.

lang-dart
String say(String from, String msg, [String device]) {
  var result = '$from says $msg';
  if (device != null) {
    result = '$result with a $device';
  }
  return result;
}

lang-dart
assert(say('Bob', 'Howdy') == 'Bob says Howdy');

lang-dart
assert(say('Bob', 'Howdy', 'smoke signal') ==
  'Bob says Howdy with a smoke signal');

lang-dart
String say(String from, String msg,
  [String device='carrier pigeon', String mood]) {
  var result = '$from says $msg';
  if (device != null) {
    result = '$result with a $device';
  }
  if (mood != null) {
    result = '$result (in a $mood mood)';
  }
  return result;
}

assert(say('Bob', 'Howdy') == 'Bob says Howdy with a carrier pigeon');

You can pass a function as a parameter to another function. For example:

lang-dart
printElement(element) {
  print(element);
}
  
var list = [1,2,3];
list.forEach(printElement); // Pass printElement as a parameter.

You can also assign a function to a variable, such as:

lang-dart
var loudify = (msg) => '!!! ${msg.toUpperCase()} !!!';
assert(loudify('hello') == '!!! HELLO !!!');

Dart is a lexically scoped language, which means that the scope of variables is determined statically, simply by the layout of the code. You can “follow the curly braces outwards” to see if a variable is in scope.

Here is an example of nested functions with variables at each scope level:

lang-dart
var topLevel = true;
main() {
    var insideMain = true;
    
    myFunction() {
      var insideFunction = true;
      
      nestedFunction() {
        var insideNestedFunction = true;
        assert(topLevel);
        assert(insideMain);
        assert(insideFunction);
        assert(insideNestedFunction);
      }
    }
}

Notice how nestedFunction() can use variables from every level, all the way up to the top level.

A closure is a function object that has access to variables in its lexical scope, even when the function is used outside of its original scope.

Functions can close over variables defined in surrounding scopes. In the following example, adder() captures the variable addBy. Wherever the returned function goes, it remembers addBy.

lang-dart
ch02/function_closure.dart
/// Returns a function that adds [addBy] to a number.
Function makeAdder(num addBy) {
  adder(num i) {
    return addBy + i;
  }
  return adder;
}

main() {
  var add2 = makeAdder(2); // Create a function that adds 2.
  var add4 = makeAdder(4); // Create a function that adds 4.

  assert(add2(3) == 5);
  assert(add4(3) == 7);
}

Each time you create a closure, that closure is a new object. This can cause problems when you want to test whether two functions are equivalent. For example, consider this code:

lang-dart
ch02/function_equality.dart
var s = 'some string';       // Create a String object.
var splitClosure1 = s.split; // Get a reference to its split() method.
var splitClosure2 = s.split; // Get another reference to its split() method.

// Because each reference to the method creates a separate closure,
// s.split != s.split, and splitClosure1 != splitClosure2.
assert(s.split != s.split);
assert(splitClosure1 != splitClosure2);

The key to comparing instance methods is to save a reference to the closure:

lang-dart
ch02/function_equality.dart
splitClosure2 = splitClosure1;
assert(splitClosure1 == splitClosure2);

Top-level and static methods are different—you can compare them by name:

lang-dart
ch02/function_equality_2.dart
foo() {}

class SomeClass {
  static void bar() {}
}

main() {
  assert(foo == foo);
  assert(SomeClass.bar == SomeClass.bar);
}

All functions return a value. If no return value is specified, the statement return null; is implicitly appended to the function body.

Dart supports the usual arithmetic operators, as shown in Table 2.3, “Arithmetic operators”.

Example:

lang-dart
ch02/arithmetic_operators.dart
assert(2 + 3 == 5);
assert(2 - 3 == -1);
assert(2 * 3 == 6);
assert(5 / 2 == 2.5);   // Result is a double
assert(5 ~/ 2 == 2);    // Result is an integer
assert(5 % 2 == 1);     // Remainder

print('5/2 = ${5~/2} remainder ${5%2}'); // 5/2 = 2 remainder 1

Dart also supports both prefix and postfix increment and decrement operators.

Example:

lang-dart
var a, b;

a = 0;  
b = ++a;         // Increment a before b gets its value.
assert(a == b);  // 1 == 1  

a = 0;
b = a++;         // Increment a AFTER b gets its value.
assert(a != b);  // 1 != 0

a = 0;
b = --a;         // Decrement a before b gets its value.
assert(a == b);  // -1 == -1

a = 0;
b = a--;         // Decrement a AFTER b gets its value.
assert(a != b) ; // -1 != 0

To test whether two objects x and y represent the same thing, use the == operator. (In the rare case where you need to know whether two objects are the exact same object, use the identical() function instead.) Here’s how the == operator works:

Here’s an example of using each of the equality and relational operators:

lang-dart
ch02/op_equality.dart
assert(2 == 2);
assert(2 != 3);
assert(3 > 2);
assert(2 < 3);
assert(3 >= 3);
assert(2 <= 3);

The as, is, and is! operators are handy for checking types at runtime.

The result of obj is T is true if obj implements the interface specified by T. For example, obj is Object is always true.

Use the as operator to cast an object to a particular type. In general, you should use it as a shorthand for an is test on an object following by an expression using that object. For example, consider the following code:

lang-dart
if (person is Person) {               // Type check
  person.firstName = 'Bob';
}

You can make the code shorter using the as operator:

lang-dart
(person as Person).firstName = 'Bob';

As you’ve already seen, you assign values using the = operator. You can also use compound assignment operators such as +=, which combine an operation with an assignment.

Here’s how compound assignment operators work:

The following example uses both assignment and compound assignment operators:

lang-dart
var a = 2;           // Assign using =
a *= 3;              // Assign and multiply: a = a * 3
assert(a == 6);

You can invert or combine boolean expressions using the logical operators.

Here’s an example of using the logical operators:

lang-dart
if (!done && (col == 0 || col == 3)) {
  // ...Do something...
}

You can manipulate the individual bits of numbers in Dart. Usually, you’d use these bitwise and shift operators with integers, as shown in Table 2.9, “Bitwise and shift operators”.

Here’s an example of using bitwise and shift operators:

lang-dart
final value = 0x22;
final bitmask = 0x0f;

assert((value & bitmask)  == 0x02);  // AND
assert((value & ~bitmask) == 0x20);  // AND NOT
assert((value | bitmask)  == 0x2f);  // OR
assert((value ^ bitmask)  == 0x2d);  // XOR
assert((value << 4)       == 0x220); // Shift left
assert((value >> 4)       == 0x02);  // Shift right

A few operators remain, most of which you’ve already seen in other examples.

Dart supports if statements with optional else statements, as the next sample shows. Also see conditional expressions (?:), which are covered in the section called “Other Operators”.

lang-dart
if (isRaining()) {
  you.bringRainCoat();
} else if (isSnowing()) {
  you.wearJacket();
} else {
  car.putTopDown();
}

Remember, unlike JavaScript, Dart treats all values other than true as false. See the section called “Booleans” for more information.

You can iterate with the standard for loop. For example:

lang-dart
ch02/flow_for_loops.dart
var message = new StringBuffer("Dart is fun");
for (var i = 0; i < 5; i++) {
  message.write('!');
}

Closures inside of Dart’s for loops capture the value of the index, avoiding a common pitfall found in JavaScript. For example, consider:

lang-dart
ch02/flow_for_loops.dart
var callbacks = [];
for (var i = 0; i < 2; i++) {
  callbacks.add(() => print(i));
}
callbacks.forEach((c) => c());

The output is 0 and then 1, as expected. In contrast, the example would print 2 and then 2 in JavaScript.

If the object that you are iterating over is an Iterable, you can use the forEach() method. Using forEach() is a good option if you don’t need to know the current iteration counter:

lang-dart
ch02/flow_for_loops.dart
candidates.forEach((candidate) => candidate.interview());

Iterable classes such as List and Set also support the for-in form of iteration, which is described in the section called “Iteration”:

lang-dart
ch02/flow_for_loops.dart
var collection = [0, 1, 2];
for (var x in collection) {
  print(x);
}

A while loop evaluates the condition before the loop:

lang-dart
while(!isDone()) {
  doSomething();
}

A do-while loop evaluates the condition after the loop:

lang-dart
do {
  printLine();
} while (!atEndOfPage());

Use break to stop looping:

lang-dart
while (true) {
  if (shutDownRequested()) break;
  processIncomingRequests();
}

Use continue to skip to the next loop iteration:

lang-dart
for (int i = 0; i < candidates.length; i++) {
  var candidate = candidates[i];
  if (candidate.yearsExperience < 5) {
    continue;
  }
  candidate.interview();
}

You might write that example differently if you’re using a Iterable such as a list or set:

lang-dart
candidates.where((c) => c.yearsExperience >= 5)
          .forEach((c) => c.interview());

Switch statements in Dart compare integer, string, or compile-time constants using ==. The compared objects must all be instances of the same class (and not of any of its subtypes), and the class must not override ==.

Each non-empty case clause ends with a break statement, as a rule. Other valid ways to end a non-empty case clause are a continue, throw, or return statement.

Use a default clause to execute code when no case clause matches:

lang-dart
var command = 'OPEN';
switch (command) {
  case 'CLOSED':
    executeClosed();
    break;
  case 'PENDING':
    executePending();
    break;
  case 'APPROVED':
    executeApproved();
    break;
  case 'DENIED':
    executeDenied();
    break;
  case 'OPEN':
    executeOpen();
    break;
  default:
    executeUnknown();
}

The following example omits the break statement in the case clause, thus generating an error:

lang-dart
var command = 'OPEN';
switch (command) {
  case 'OPEN':
    executeOpen();
    // ERROR: Missing break causes an exception to be thrown!!

  case 'CLOSED':
    executeClosed();
    break;
}

However, Dart does support empty case clauses, allowing a form of fall-through:

lang-dart
var command = 'CLOSED';
switch (command) {
  case 'CLOSED':     // Empty case falls through.
  case 'NOW_CLOSED':
    // Runs for both CLOSED and NOW_CLOSED.
    executeNowClosed();
    break;
}

If you really want fall-through, you can use a continue statement and a label:

lang-dart
var command = 'CLOSED';
switch (command) {
  case 'CLOSED':
    executeClosed();
    continue nowClosed; // Continues executing at the nowClosed label.

nowClosed:
  case 'NOW_CLOSED':
    // Runs for both CLOSED and NOW_CLOSED.
    executeNowClosed();
    break;
}

A case clause can have local variables, which are visible only inside the scope of that clause.

Use an assert statement to disrupt normal execution if a boolean condition is false. You can find examples of assert statements throughout this tour. Here are some more:

lang-dart
assert(text != null);  // Make sure the variable has a non-null value.
assert(number < 100);  // Make sure the value is less than 100.
assert(urlString.startsWith('https')); // Make sure this is an HTTPS URL.

Inside the parentheses after assert, you can put any expression that resolves to a boolean value or to a function. If the expression’s value or function’s return value is true, the assertion succeeds and execution continues. Otherwise, the assertion fails and an exception (an AssertionError) is thrown.

Here’s an example of throwing, or raising, an exception:

lang-dart
throw new ExpectException('Value must be greater than zero');

You can also throw arbitrary objects:

lang-dart
throw 'Out of llamas!';

Because throwing an exception is an expression, you can throw exceptions in => statements, as well as anywhere else that allows expressions:

lang-dart
distanceTo(Point other) => throw new UnimplementedError();

Catching, or capturing, an exception stops the exception from propagating. Catching an exception gives you a chance to handle it:

lang-dart
try {
  breedMoreLlamas();
} on OutOfLlamasException {
  buyMoreLlamas();
}

To handle code that can throw more than one type of exception, you can specify multiple catch clauses. The first catch clause that matches the thrown object’s type handles the exception. If the catch clause does not specify a type, that clause can handle any type of thrown object:

lang-dart
try {
  breedMoreLlamas();
} on OutOfLlamasException {           // A specific exception
  buyMoreLlamas();
} on Exception catch(e) {             // Anything else that is an exception
  print('Unknown exception: $e');
} catch(e) {                          // No specified type, handles all
  print('Something really unknown: $e');
}

As the preceding code shows, you can use either on or catch or both. Use on when you need to specify the exception type. Use catch when your exception handler needs the exception object.

To ensure that some code runs whether or not an exception is thrown, use a finally clause. If no catch clause matches the exception, the exception is propagated after the finally clause runs:

lang-dart
try {
  breedMoreLlamas();
} finally {
  cleanLlamaStalls();  // Always clean up, even if an exception is thrown.
}

The finally clause runs after any matching catch clauses:

lang-dart
try {
  breedMoreLlamas();
} catch(e) {
  print('Error: $e');  // Handle the exception first.
} finally {
  cleanLlamaStalls();  // Then clean up.
}

Learn more by reading the section called “Exceptions”.

Here’s how you declare instance variables:

lang-dart
ch02/instance_variables.dart
class Point {
  num x;      // Declare an instance variable (x), initially null.
  num y;      // Declare y, initially null.
  num z = 0;  // Declare z, initially 0.
}

All uninitialized instance variables have the value null.

All instance variables generate an implicit getter method. Non-final, non-const instance variables also generate an implicit setter method. For details, see the section called “Getters and setters”.

lang-dart
ch02/instance_variables.dart
class Point {
  num x;
  num y;
}

main() {
  var point = new Point();
  point.x = 4;             // Use the setter method for x.
  assert(point.x == 4);    // Use the getter method for x.
  assert(point.y == null); // Values default to null.
}

If you initialize an instance variable where it is declared (instead of in a constructor or method), the value is set when the instance is created, which is before the constructor and its initializer list execute.

Declare a constructor by creating a function with the same name as its class (plus, optionally, an additional identifier as described in the section called “Named constructors”). The most common form of constructor, the generative constructor, creates a new instance of a class:

lang-dart
ch02/constructor_long_way.dart
class Point {
  num x;
  num y;

  Point(num x, num y) {
    // There's a better way to do this, stay tuned.
    this.x = x;
    this.y = y;
  }
}

The this keyword refers to the current instance.

The pattern of assigning a constructor argument to an instance variable is so common, Dart has syntactic sugar to make it easy:

lang-dart
class Point {
  num x;
  num y;

  // Syntactic sugar for setting x and y before the constructor body runs.
  Point(this.x, this.y);
}

lang-dart
ch02/named_constructor.dart
class Point {
  num x;
  num y;

  Point(this.x, this.y);

  // Named constructor
  Point.fromJson(Map json) {
    x = json['x'];
    y = json['y'];
  }
}

lang-dart
ch02/op_as.dart
class Person {
  Person.fromJson(Map data) {
    print('in Person');
  }
}

class Employee extends Person {
  // Person does not have a default constructor;
  // you must call super.fromJson(data).
  Employee.fromJson(Map data) : super.fromJson(data) {
    print('in Employee');
  }
}

main() {
  var emp = new Employee.fromJson({});

  // Prints:
  // in Person
  // in Employee
}

lang-dart
ch02/initializer_list.dart
class Point {
  num x;
  num y;

  Point(this.x, this.y);

  // Initializer list sets instance variables before the constructor body runs.
  Point.fromJson(Map json) : x = json['x'], y = json['y'] {
    print('In Point.fromJson(): ($x, $y)');
  }
}

lang-dart
ch02/along_x_axis.dart
class Point {
  num x;
  num y;

  Point(this.x, this.y);                // The main constructor for this class.
  Point.alongXAxis(num x) : this(x, 0); // Delegates to the main constructor.
}

lang-dart
ch02/immutable_point.dart
class ImmutablePoint {
  final num x;
  final num y;
  const ImmutablePoint(this.x, this.y);
  static final ImmutablePoint origin = const ImmutablePoint(0, 0);
}

lang-dart
ch02/factory_constructor.dart
class Logger {
  final String name;
  bool mute = false;

  // _cache is library-private, thanks to the _ in front of its name.
  static final Map<String, Logger> _cache = <String, Logger>{};
  
  factory Logger(String name) {
    if (_cache.containsKey(name)) {
      return _cache[name];
    } else {
      final logger = new Logger._internal(name);
      _cache[name] = logger;
      return logger;
    }
  }
  
  Logger._internal(this.name);
  
  void log(String msg) {
    if (!mute) {
      print(msg);
    }
  }
}

lang-dart
ch02/factory_constructor.dart
var logger = new Logger('UI');
logger.log('Button clicked');

Methods are functions that provide behavior for an object.

lang-dart
ch02/distance_to.dart
import 'dart:math';

class Point {
  num x;
  num y;
  Point(this.x, this.y);

  num distanceTo(Point other) {
    var dx = x - other.x;
    var dy = y - other.y;
    return sqrt(dx * dx + dy * dy);
  }
}

lang-dart
ch02/rectangle.dart
class Rectangle {
  num left;
  num top;
  num width;
  num height;

  Rectangle(this.left, this.top, this.width, this.height);

  // Define two calculated properties: right and bottom.
  num get right             => left + width;
      set right(num value)  => left = value - width;
  num get bottom            => top + height;
      set bottom(num value) => top = value - height;
}

main() {
  var rect = new Rectangle(3, 4, 20, 15);
  assert(rect.left == 3);
  rect.right = 12;
  assert(rect.left == -8);
}

lang-dart
ch02/doer.dart
abstract class Doer {
  // ...Define instance variables and methods...
 
  void doSomething(); // Define an abstract method.
}

class EffectiveDoer extends Doer {
  void doSomething() {
    // ...Provide an implementation, so the method is not abstract here...
  }
}

lang-dart
ch02/vector.dart
class Vector {
  final int x;
  final int y;
  const Vector(this.x, this.y);

  Vector operator +(Vector v) { // Overrides + (a + b).
    return new Vector(x + v.x, y + v.y);
  }

  Vector operator -(Vector v) { // Overrides - (a - b).
    return new Vector(x - v.x, y - v.y);
  }
}

main() {
  final v = new Vector(2,3);
  final w = new Vector(2,2);

  assert(v.x == 2 && v.y == 3);         // v   == (2,3)
  assert((v+w).x == 4 && (v+w).y == 5); // v+w == (4,5)
  assert((v-w).x == 0 && (v-w).y == 1); // v-w == (0,1)
}

Use the abstract modifier to define an abstract class—a class that can’t be instantiated. Abstract classes are useful for defining interfaces, often with some implementation. If you want your abstract class to appear to be instantiable, define a factory constructor.

Abstract classes often have abstract methods. Here’s an example of declaring an abstract class that has an abstract method:

lang-dart
ch02/abstract.dart
// This class is declared abstract and thus can't be instantiated.
abstract class AbstractContainer {
  // ...Define constructors, fields, methods...

  void updateChildren(); // Abstract method.
}

The following class isn’t abstract, and thus can be instantiated even though it defines an abstract method:

lang-dart
ch02/abstract.dart
class SpecializedContainer extends AbstractContainer {
  // ...Define more constructors, fields, methods...

  void updateChildren() {
    // ...Implement updateChildren()...
  }
// Abstract method causes a warning but doesn't prevent instantiatation.
  void doSomething(); 
}

Every class implicitly defines an interface containing all the instance members of the class and of any interfaces it implements. If you want to create a class A that supports class B’s API without inheriting B’s implementation, class A should implement the B interface.

A class implements one or more interfaces by declaring them in an implements clause and then providing the APIs required by the interfaces. For example:

lang-dart
ch02/imposter.dart
// A person. The implicit interface contains greet().
class Person {
  final _name;          // In the interface, but visible only in this library,
  Person(this._name);   // Not in the interface, since this is a constructor.
  String greet(who) => 'Hello, $who. I am $_name.'; // In the interface.
}

// An implementation of the Person interface.
class Imposter implements Person {
  final _name = "";      // We have to define this, but we don't use it.
  String greet(who) => 'Hi $who. Do you know who I am?';
}

greetBob(Person person) => person.greet('bob');

main() {
  print(greetBob(new Person('kathy')));
  print(greetBob(new Imposter()));
}

Here’s an example of specifying that a class implements multiple interfaces:

lang-dart
ch02/point_interfaces.dart
class Point implements Comparable, Location {
  // ...
}

Use extends to create a subclass, and super to refer to the superclass:

lang-dart
smart_tv.dart
class Television {
  void turnOn() {
    _illuminateDisplay();
    _activateIrSensor();
  }
  ...
}

class SmartTelevision extends Television {
  void turnOn() {
    super.turnOn();
    _bootNetworkInterface();
    _initializeMemory();
    _upgradeApps();
  }
  ...
}

Subclasses can override instance methods, getters, and setters. Here’s an example of overriding the Object class’s noSuchMethod() method, which is called whenever code attempts to use a non-existent method or instance variable:

lang-dart
ch02/no_such_method.dart
class A {
  // Unless you override noSuchMethod, using a non-existent member
  // results in a NoSuchMethodError.
  void noSuchMethod(Invocation mirror) {
    print('You tried to use a non-existent member: ${mirror.memberName}');
  }
}

Use the static keyword to implement class-wide variables and methods.

lang-dart
ch02/color.dart
class Color {
  static const RED = const Color('red'); // A constant static variable.
  final String name;                     // An instance variable.
  const Color(this.name);                // A constant constructor.
}

main() {
  assert(Color.RED.name == 'red');
}

lang-dart
ch02/point.dart
import 'dart:math';

class Point {
  num x;
  num y;
  Point(this.x, this.y);

  static num distanceBetween(Point a, Point b) {
    var dx = a.x - b.x;
    var dy = a.y - b.y;
    return sqrt(dx * dx + dy * dy);
  }
}

main() {
  var a = new Point(2, 2);
  var b = new Point(4, 4);
  var distance = Point.distanceBetween(a,b);
  assert(distance < 2.9 && distance > 2.8);
}

Because types are optional in Dart, you never have to use generics. You might want to, though, for the same reason you might want to use other types in your code: types (generic or not) let you document and annotate your code, making your intent clearer.

For example, if you intend for a list to contain only strings, you can declare it as List<String> (read that as “list of string”). That way you, your fellow programmers, and your tools (such as Dart Editor and the Dart VM in checked mode) can detect that assigning a non-string to the list is probably a mistake. Here’s an example:

lang-dart
ch02/generics.dart
var names = new List<String>();
names.addAll(['Seth', 'Kathy', 'Lars']);
// ...
names.add(42); // Fails in checked mode (succeeds in production mode).

Another reason for using generics is to reduce code duplication. Generics let you share a single interface and implementation between many types, while still taking advantage of checked mode and static analysis early warnings. For example, say you create an interface for caching an object:

lang-dart
abstract class ObjectCache {
  Object getByKey(String key);
  setByKey(String key, Object value);
}

You discover that you want a string-specific version of this interface, so you create another interface:

lang-dart
abstract class StringCache {
  String getByKey(String key);
  setByKey(String key, String value);
}

Later, you decide you want a number-specific version of this interface... You get the idea.

Generic types can save you the trouble of creating all these interfaces. Instead, you can create a single interface that takes a type parameter:

lang-dart
abstract class Cache<T> {
  T getByKey(String key);
  setByKey(String key, T value);
}

In this code, T is the stand-in type. It’s a placeholder that you can think of as a type that a developer will define later.

List and map literals can be parameterized. Parameterized literals are just like the literals you’ve already seen, except that you add <type> (for lists) or <keyType, valueType> (for maps) before the opening bracket. You might use parameterized literals when you want type warnings in checked mode. Here is example of using typed literals:

lang-dart
var names = <String>['Seth', 'Kathy', 'Lars'];
var pages = <String, String>{
    'index.html':'Homepage',
    'robots.txt':'Hints for web robots',
    'humans.txt':'We are people, not machines' };

To specify one or more types when using a constructor, put the types in angle brackets (<...>) just after the class name. For example:

lang-dart
var names = new List<String>();
names.addAll(['Seth', 'Kathy', 'Lars']);
var nameSet = new Set<String>.from(names);

The following code creates a map that has integer keys and values of type View:

lang-dart
var views = new Map<int, View>();

Dart generic types are reified, which means that they carry their type information around at runtime. For example, you can test the type of a collection, even in production mode:

lang-dart
var names = new List<String>();
names.addAll(['Seth', 'Kathy', 'Lars']);
print(names is List<String>); // true

However, the is expression checks the type of the collection only—not of the objects inside it. In production mode, a List<String> might have some non-string items in it. The solution is to either check each item’s type or wrap item-manipulation code in an exception handler (see the section called “Exceptions”).

For more information about generics, see Optional Types in Dart.

Use import to specify how a namespace from one library is used in the scope of another library.

For example, Dart web apps generally use the dart:html library, which they can import like this:

lang-dart
ch02/libraries/using_libraries.dart
import 'dart:html';

The only required argument to import is a URI^[1] specifying the library. For built-in libraries, the URI has the special dart: scheme. For other libraries, you can use a file system path or the package: scheme. The package: scheme specifies libraries provided by a package manager such as the pub tool. For example:

lang-dart
ch02/libraries/using_schemes.dart, mylib, utils
import 'dart:io';
import 'package:mylib/mylib.dart';
import 'package:utils/utils.dart';

lang-dart
ch02/libraries/library_prefix.dart, lib1, lib2
import 'package:lib1/lib1.dart';
import 'package:lib2/lib2.dart' as lib2;
// ...
var element1 = new Element();      // Uses Element from lib1.
var element2 = new lib2.Element(); // Uses Element from lib2.

lang-dart
ch02/libraries/library_partil.dart, lib1, lib2
import 'package:lib1/lib1.dart' show foo, bar; // Import only foo and bar.
import 'package:lib2/lib2.dart' hide foo;      // Import all names EXCEPT foo.

Use library to name a library, and part to specify additional files in the library.

lang-dart
ch02/ballgame.dart
library ballgame;   // Declare that this is a library named ballgame.

import 'dart:html'; // This app uses the HTML library.
// ...Code goes here...

lang-dart
ch02/ballgame.dart
library ballgame;

import 'dart:html';
// ...Other imports go here...

part 'ball.dart';
part 'util.dart';

// ...Code might go here...

lang-dart
ch02/ball.dart
part of ballgame;

// ...Code goes here...

lang-dart
ch02/util.dart
part of ballgame;

// ...Code goes here...

lang-dart
ch02/french.dart, togo.dart, french_togo.dart
// In french.dart:
library french;
hello() => print('Bonjour!');
goodbye() => print('Au Revoir!');

// In togo.dart:
library togo;
import 'french.dart';
export 'french.dart' show hello;

// In another .dart file:
import 'togo.dart';

void main() {
  hello();   //print bonjour
  goodbye(); //FAIL
}

A single-line comment begins with //. Everything between // and the end of line is ignored by the Dart compiler.

lang-dart
main() {
  // TODO: refactor into an AbstractLlamaGreetingFactory?
  print('Welcome to my Llama farm!');
}

A multi-line comment begins with /* and ends with */. Everything between /* and */ is ignored by the Dart compiler (unless the comment is a documentation comment; see the next section). Multi-line comments can nest.

lang-dart
ch02/multi_line_comments.dart
main() {
  /*
   * This is a lot of work. Consider raising chickens.

  Llama larry = new Llama();
  larry.feed();
  larry.exercise();
  larry.clean();
   */
}

Documentation comments are multi-line or single-line comments that begin with /** or ///. Using /// on consecutive lines has the same effect as a multi-line doc comment.

Inside a documentation comment, the Dart compiler ignores all text unless it is enclosed in brackets. Using brackets, you can refer to classes, methods, fields, top-level variables, functions, and parameters. The names in brackets are resolved in the lexical scope of the documented program element.

Here is an example of documentation comments with references to other classes and arguments:

lang-dart
ch02/doc_comments.dart
/**
 * The llama (Lama glama) is a domesticated South American
 * camelid, widely used as a meat and pack animal by Andean
 * cultures since pre-Hispanic times.
 */
class Llama {
  String name;

  /**
   * Feeds your llama [Food].
   * 
   * The typical llama eats one bale of hay per week.
   */
  void feed(Food food) {
    // ...
  }

  /// Exercises your llama with an [activity] for
  /// [timeLimit] minutes.
  void exercise(Activity activity, int timeLimit) {
    // ...
  }
}

In the generated documentation, [Food] becomes a link to the API docs for the Food class.

To parse Dart code and generate HTML documentation, you can use Dart Editor, which in turn uses the SDK’s dartdoc package. For an example of generated documentation, see the Dart API documentation.