Chapter 3. A Tour of the Dart Libraries

You can find particular locations within a string, as well as check whether a string begins with or ends with a particular pattern. For example:

lang-dart
ch03/string-tests.dart
// Check whether a string contains another string.
assert('Never odd or even'.contains('odd'));

// Does a string start with another string?
assert('Never odd or even'.startsWith('Never'));

// Does a string end with another string?
assert('Never odd or even'.endsWith('even'));

// Find the location of a string inside a string.
assert('Never odd or even'.indexOf('odd') == 6);

You can get the individual characters or UTF-16 code units from a string as Strings or ints, respectively.

You can also extract a substring or split a string into a list of substrings:

lang-dart
ch03/string-tests.dart
// Grab a substring.
assert('Never odd or even'.substring(6, 9) == 'odd');

// Split a string using a string pattern.
var parts = 'structured web apps'.split(' ');
assert(parts.length == 3);
assert(parts[0] == 'structured');

// Get a character (as a string) by index.
assert('Never odd or even'[0] == 'N');

// Use split() with an empty string parameter to get a list of
// all characters (as Strings); good for iterating.
for (var char in 'hello'.split('')) {
  print(char);
}

// Get all the characters in the string as a list of UTF-16 code units.
// Some characters might require two code units.
var codeUnitList = 'Never odd or even'.codeUnits.toList();
assert(codeUnitList[0] == 78);

You can easily convert strings to their uppercase and lowercase variants:

lang-dart
ch03/string-tests.dart
// Convert to uppercase.
assert('structured web apps'.toUpperCase() == 'STRUCTURED WEB APPS');

// Convert to lowercase.
assert('STRUCTURED WEB APPS'.toLowerCase() == 'structured web apps');

Remove all leading and trailing white space with trim(). To check whether a string is empty (length is zero), use isEmpty.

lang-dart
ch03/string-tests.dart
// Trim a string.
assert('  hello  '.trim() == 'hello');

// Check whether a string is empty.
assert(''.isEmpty);

// Strings with only white space are not empty.
assert(!'  '.isEmpty);

Strings are immutable objects, which means you can create them but you can’t change them. If you look closely at the String API docs, you’ll notice that none of the methods actually changes the state of a String. For example, the method replaceAll() returns a new String without changing the original String:

lang-dart
ch03/string-tests.dart
var greetingTemplate = 'Hello, NAME!';
var greeting = greetingTemplate.replaceAll(new RegExp('NAME'), 'Bob');

assert(greeting != greetingTemplate); // greetingTemplate didn't change.

To programmatically generate a string, you can use StringBuffer. A StringBuffer doesn’t generate a new String object until toString() is called.

lang-dart
ch03/string-tests.dart
var sb = new StringBuffer();

sb..write('Use a StringBuffer ')
  ..writeAll(['for ', 'efficient ', 'string ', 'creation'])
  ..write('.');

var fullString = sb.toString();

assert(fullString ==
    'Use a StringBuffer for efficient string creation.');

The RegExp class provides the same capabilities as JavaScript regular expressions. Use regular expressions for efficient searching and pattern matching of strings.

lang-dart
ch03/string-tests.dart
// A regular expression for one or more digits
var numbers = new RegExp(r'\d+');

var allCharacters = 'llamas live fifteen to twenty years';
var someDigits = 'llamas live 15 to 20 years';

// Contains() can use a regular expression.
assert(!allCharacters.contains(numbers));
assert(someDigits.contains(numbers));

// Replace every match with another string.
var exedOut = someDigits.replaceAll(numbers, 'XX');
assert(exedOut == 'llamas live XX to XX years');

You can work directly with the RegExp class, too. The Match class provides access to a regular expression match.

lang-dart
ch03/string-tests.dart
var numbers = new RegExp(r'\d+');
var someDigits = 'llamas live 15 to 20 years';

// Check whether the reg exp has a match in a string.
assert(numbers.hasMatch(someDigits));

// Loop through all matches.
for (var match in numbers.allMatches(someDigits)) {
  print(match.group(0)); // 15, then 20
}

Refer to the String API docs for a full list of methods. Also see the API docs for StringBuffer, Pattern, RegExp, and Match.

As the language tour shows, you can use literals to create and initialize lists. Alternatively, use one of the List constructors. The List class also defines several methods for adding items to and removing items from lists.

lang-dart
ch03/list-tests.dart
// Use a List constructor.
var vegetables = new List();

// Or simply use a list literal.
var fruits = ['apples', 'oranges'];

// Add to a list.
fruits.add('kiwis');

// Add multiple items to a list.
fruits.addAll(['grapes', 'bananas']);

// Get the list length.
assert(fruits.length == 5);

// Remove a single item.
var appleIndex = fruits.indexOf('apples');
fruits.removeAt(appleIndex);
assert(fruits.length == 4);

// Remove all elements from a list.
fruits.clear();
assert(fruits.length == 0);

Use indexOf() to find the index of an object in a list:

lang-dart
ch03/list-tests.dart
var fruits = ['apples', 'oranges'];

// Access a list item by index.
assert(fruits[0] == 'apples');

// Find an item in a list.
assert(fruits.indexOf('apples') == 0);

Sort a list using the sort() method. You must provide a sorting function that compares two objects. This sorting function must return < 0 for smaller, 0 for the same, and > 0 for bigger. The following example uses compareTo(), which is defined by Comparable and implemented by String.

lang-dart
ch03/list-tests.dart
var fruits = ['bananas', 'apples', 'oranges'];

// Sort a list.
fruits.sort((a, b) => a.compareTo(b));
assert(fruits[0] == 'apples');

Lists are parameterized types, so you can specify the type that a list should contain:

lang-dart
ch03/list-tests.dart
// This list should contain only strings.
var fruits = new List<String>();

fruits.add('apples');
var fruit = fruits[0];
assert(fruit is String);

// Generates static analysis warning, num is not a string.
fruits.add(5);  // BAD: Throws exception in checked mode.

Refer to the List API docs for a full list of methods.

A set in Dart is an unordered collection of unique items. Because a set is unordered, you can’t get a set’s items by index (position).

lang-dart
ch03/set-tests.dart
var ingredients = new Set();
ingredients.addAll(['gold', 'titanium', 'xenon']);
assert(ingredients.length == 3);

// Adding a duplicate item has no effect.
ingredients.add('gold');
assert(ingredients.length == 3);

// Remove an item from a set.
ingredients.remove('gold');
assert(ingredients.length == 2);

Use contains() and containsAll() to check whether one or more objects are in a set:

lang-dart
ch03/set-tests.dart
var ingredients = new Set();
ingredients.addAll(['gold', 'titanium', 'xenon']);

// Check whether an item is in the set.
assert(ingredients.contains('titanium'));

// Check whether all the items are in the set.
assert(ingredients.containsAll(['titanium', 'xenon']));

An intersection is a set whose items are in two other sets.

lang-dart
ch03/set-tests.dart
var ingredients = new Set();
ingredients.addAll(['gold', 'titanium', 'xenon']);

// Create the intersection of two sets.
var nobleGases = new Set.from(['xenon', 'argon']);
var intersection = ingredients.intersection(nobleGases);
assert(intersection.length == 1);
assert(intersection.contains('xenon'));

Refer to the Set API docs for a full list of methods.

A map, commonly known as a dictionary or hash, is an unordered collection of key-value pairs. Maps associate a key to some value for easy retrieval. Unlike in JavaScript, Dart objects are not maps.

You can declare a map using a terse literal syntax, or you can use a traditional constructor:

lang-dart
ch03/map-1.dart
// Map literals use strings as keys.
var hawaiianBeaches = {
  'oahu' : ['waikiki', 'kailua', 'waimanalo'],
  'big island' : ['wailea bay', 'pololu beach'],
  'kauai' : ['hanalei', 'poipu']
};

// Maps can be built from a constructor.
var searchTerms = new Map();

// Maps are parameterized types; you can specify what types
// the key and value should be.
var nobleGases = new Map<int, String>();

You add, get, and set map items using the bracket syntax. Use remove() to remove a key and its value from a map. [PENDING: It’s questionable that this example uses containsKey before containsKey is discussed.]

lang-dart
ch03/map-1.dart
var nobleGases = new Map<int, String>();

// Maps from constructors can use any object as a key.
// Integers and strings are common key types.
nobleGases[54] = 'xenon';

// Retrieve a value with a key.
assert(nobleGases[54] == 'xenon');

// Check whether a map contains a key.
assert(nobleGases.containsKey(54));

// Remove a key and its value.
nobleGases.remove(54);
assert(!nobleGases.containsKey(54));

You can retrieve all the values or all the keys from a map:

lang-dart
ch03/map-1.dart
var hawaiianBeaches = {
  'oahu' : ['waikiki', 'kailua', 'waimanalo'],
  'big island' : ['wailea bay', 'pololu beach'],
  'kauai' : ['hanalei', 'poipu']
};

// Get all the keys as an unordered collection (an Iterable).
var keys = hawaiianBeaches.keys;

assert(keys.length == 3);
assert(new Set.from(keys).contains('oahu'));

// Get all the values as an unordered collection (an Iterable of Iterables).
var values = hawaiianBeaches.values;
assert(values.length == 3);
assert(values.any((v) => v.indexOf('waikiki') != -1));

To check whether a map contains a key, use containsKey(). Because map values can be null, you cannot rely on simply getting the value for the key and checking for null to determine the existence of a key.

lang-dart
ch03/map-1.dart
var hawaiianBeaches = {
  'oahu' : ['waikiki', 'kailua', 'waimanalo'],
  'big island' : ['wailea bay', 'pololu beach'],
  'kauai' : ['hanalei', 'poipu']
};

assert(hawaiianBeaches.containsKey('oahu'));
assert(!hawaiianBeaches.containsKey('florida'));

Use the putIfAbsent() method when you want to assign a value to a key if and only if the key does not already exist in a map. You must provide a function that returns the value.

lang-dart
ch03/map-1.dart
var teamAssignments = {};
teamAssignments.putIfAbsent('Catcher', () => pickToughestKid());
assert(teamAssignments['Catcher'] != null);

Refer to the Map API docs for a full list of methods.

List, Set, and Map share common functionality found in many collections. Some of this common functionality is defined by the Iterable class, which List and Set implement.

Use isEmpty to check whether a list, set, or map has no items:

lang-dart
ch03/collection-isEmpty.dart
var teas = ['green', 'black', 'chamomile', 'earl grey'];
assert(!teas.isEmpty);

To apply a function to each item in a list, set, or map, you can use forEach():

lang-dart
ch03/collection-apply-function.dart
var teas = ['green', 'black', 'chamomile', 'earl grey'];

teas.forEach((tea) => print('I drink $tea'));

When you invoke forEach() on a map, your function must take two arguments (the key and value):

lang-dart
ch03/map-1.dart
// NOTE: Do not depend on iteration order.
hawaiianBeaches.forEach((k,v) {
  print('I want to visit $k and swim at $v');
  // I want to visit oahu and swim at [waikiki, kailua, waimanalo], etc.
});

An alternative for Iterables is the map() method, which gives you all the results in a single object:

lang-dart
ch03/collection-apply-function.dart
var teas = ['green', 'black', 'chamomile', 'earl grey'];

var loudTeas = teas.map((tea) => tea.toUpperCase());
loudTeas.forEach(print);

To force your function to be called immediately on each item, use map().toList() or map().toSet():

lang-dart
ch03/collection-apply-function.dart
var loudTeaList = teas.map((tea) => tea.toUpperCase()).toList();

Use Iterable’s where() method to get all the items that match a condition. Use Iterable’s any() and every() methods to check whether some or all items match a condition.

lang-dart
ch03/collection-any-every.dart
var teas = ['green', 'black', 'chamomile', 'earl grey'];

// Chamomile is not caffeinated.
bool isDecaffeinated(String teaName) => teaName == 'chamomile';

// Use where() to find only the items that return true
// from the provided function.
var decaffeinatedTeas = teas.where((tea) => isDecaffeinated(tea));
// or teas.where(isDecaffeinated)

// Use any() to check whether at least one item in the collection
// satisfies a condition.
assert(teas.any(isDecaffeinated));

// Use every() to check whether all the items in a collection
// satisfy a condition.
assert(!teas.every(isDecaffeinated));

For a full list of methods, refer to the Iterable API docs, as well as those for List, Set, and Map.

To encode and decode characters except those with special meaning in a URI (such as /, :, &, #), use the encodeFull() and decodeFull() methods. These methods are good for encoding or decoding a fully qualified URI, leaving intact special URI characters.

lang-dart
code/ch03/encodeUri.dart
main() {
  var uri = 'http://example.org/api?foo=some message';
  var encoded = Uri.encodeFull(uri);
  assert(encoded == 'http://example.org/api?foo=some%20message');

  var decoded = Uri.decodeFull(encoded);
  assert(uri == decoded);
}

Notice how only the space between some and message was encoded.

To encode and decode all of a string’s characters that have special meaning in a URI, including (but not limited to) /, &, and :, use the encodeComponent() and decodeComponent() methods.

lang-dart
code/ch03/encodeUriComponents.dart
main() {
  var uri = 'http://example.org/api?foo=some message';
  var encoded = Uri.encodeComponent(uri);
  assert(encoded == 'http%3A%2F%2Fexample.org%2Fapi%3Ffoo%3Dsome%20message');

  var decoded = Uri.decodeComponent(encoded);
  assert(uri == decoded);
}

Notice how every special character is encoded. For example, / is encoded to %2F.

If you have a Uri object or a URI string, you can get its parts using Uri fields such as path. To create a Uri from a string, use the parse() static method:

lang-dart
code/ch03/parseUri.dart
main() {
  var uri = Uri.parse('http://example.org:8080/foo/bar#frag');

  assert(uri.scheme   == 'http');
  assert(uri.host     == 'example.org');
  assert(uri.path     == '/foo/bar');
  assert(uri.fragment == 'frag');
  assert(uri.origin   == 'http://example.org:8080');
}

See the Uri API docs for more URI components that you can get.

You can build up a URI from individual parts using the Uri() constructor:

lang-dart
code/ch03/uriFromComponents.dart
main() {
  var uri = new Uri(scheme: 'http', host: 'example.org', 
                    path: '/foo/bar', fragment: 'frag');
  assert(uri.toString() == 'http://example.org/foo/bar#frag');
}

Implement the Comparable interface to indicate that an object can be compared to another object, usually for sorting. The compareTo() method returns < 0 for smaller, 0 for the same, and > 0 for bigger.

lang-dart
ch03/comparable.dart
class Line implements Comparable {
  final length;
  const Line(this.length);
  int compareTo(Line other) => length - other.length;
}

main() {
  var short = const Line(1);
  var long = const Line(100);
  assert(short.compareTo(long) < 0);
}

Each object in Dart automatically provides an integer hash code, and thus can be used as a key in a map. However, you can override the hashCode getter to generate a custom hash code. If you do, be sure to override the == operator, as well. Objects that are equal (via ==) must have identical hash codes. A hash code doesn’t have to be unique, but it should be well distributed.

Note: There’s disagreement over whether to include identical() in the == implementation. It might improve speed. They don’t do identical() automatically because, by convention, NaN != NaN.

lang-dart
ch03/map-keys.dart
class Person {
  String firstName, lastName;

  Person(this.firstName, this.lastName);

  // Override hashCode using strategy from Effective Java, Chapter 11.
  int get hashCode {
    int result = 17;
    result = 37 * result + firstName.hashCode;
    result = 37 * result + lastName.hashCode;
    return result;
  }

  // Always implement operator== if you override hashCode.
  bool operator==(other) {
    if (identical(other, this)) return true;
    return (other.firstName == firstName && other.lastName == lastName);
  }
}

main() {
  var p1 = new Person('bob', 'smith');
  var p2 = new Person('bob', 'smith');
  assert(p1.hashCode == p2.hashCode);
}

The Iterable and Iterator classes support for-in loops. Extend (if possible) or implement Iterable whenever you create a class that can provide Iterators for use in for-in loops. Implement Iterator to define the actual iteration ability.

lang-dart
ch03/iterator.dart
class Process {
  // Represents a process...
}

class ProcessIterator implements Iterator<Process> {
  Process current;
  bool moveNext() {
    return false;
  }
}

// A mythical class that lets you iterate through all processes.
// Extends an Iterable subclass.
class Processes extends DoubleLinkedQueue<Process> {
  final Iterator<Process> iterator = new ProcessIterator();
}

main() {
  // Iterable objects can be used with for-in.
  for (var process in new Processes()) {
    // Do something with the process.
  }
}

To manipulate an element, you first need an object that represents it. You can get this object using a query.

Find one or more elements using the top-level functions query() and queryAll(). You can query by ID, class, tag, name, or any combination of these. The CSS Selector Specification guide defines the formats of the selectors such as using a # prefix to specify IDs and a period (.) for classes.

The query() function returns the first element that matches the selector, while queryAll() returns a collection of elements that match the selector.

lang-dart
ch03_html/ch03_html.dart
Element elem1 = query('#an-id');           // Find an element by id (an-id).
Element elem2 = query('.a-class');         // Find an element by class (a-class).
List<Element> elems1 = queryAll('div');    // Find all elements by tag (<div>).
List<Element> elems2 = queryAll('input[type="text"]'); // Find all text inputs.

// Find all elements with the CSS class 'class' inside of a <p>
// that is inside an element with the ID 'id'.
List<Element> elems3 = queryAll('#id p.class');

You can use properties to change the state of an element. Node and its subtype Element define the properties that all elements have. For example, all elements have classes, hidden, id, innerHtml, style, text, and title properties. Subclasses of Element define additional properties, such as the href property of AnchorElement.

Consider this example of specifying an anchor element in HTML:

lang-dart
ch03_html/ch03_html.dart
<a id="example" href="http://example.com">link text</a>

This <a> tag specifies an element with an href attribute and a text node (accessible via a text property) that contains the string “linktext”. To change the URL that the link goes to, you can use AnchorElement’s href property:

lang-dart
ch03_html/ch03_html.dart
query('#example').href = 'http://dartlang.org';

Often you need to set properties on multiple elements. For example, the following code sets the hidden property of all elements that have a class of “mac”, “win”, or “linux”. Setting the hidden property to true has the same effect as adding display:none to the CSS.

lang-dart
ch03_html/ch03_html.dart
<!-- In HTML: -->
<p>
  <span class="os linux">Words for Linux</span>
  <span class="os mac">Words for Mac</span>
  <span class="os win">Words for Windows</span>
</p>

// In Dart:
final osList = ['mac', 'win', 'linux'];

var userOs = 'linux'; // In real code you'd programmatically determine this.

for (var os in osList) {            // For each possible OS...
  bool shouldShow = (os == userOs); // Does this OS match the user's OS?
  for (var elem in queryAll('.$os')) { // Find all elements for this OS.
    elem.hidden = !shouldShow;      // Show or hide each element.
  }
}

When the right property isn’t available or convenient, you can use Element’s attributes property. This property has the type AttributeMap, which implements a map with keys that are strings (attribute names) and values that it automatically converts to strings. For a list of attribute names and their meanings, see the MDN Attributes page. Here’s an example of setting an attribute’s value:

lang-dart
ch03_html/ch03_html.dart
elem.attributes['someAttribute'] = 'someValue';

You can add to existing HTML pages by creating new elements and attaching them to the DOM. Here’s an example of creating a paragraph (<p>) element:

lang-dart
ch03_html/ch03_html.dart
var elem = new ParagraphElement();
elem.text = 'Creating is easy!';

You can also create an element by parsing HTML text. Any child elements are also parsed and created.

lang-dart
ch03_html/ch03_html.dart
var elem2 = new Element.html('<p>Creating <em>is</em> easy!</p>');

Note that elem2 is a ParagraphElement in the above example.

Attach the newly created element to the document by assigning a parent to the element. You can add an element to any existing element’s children. In the following example, body is an element, and its child elements are accessible (as a List<Element>) from the children property.

lang-dart
ch03_html/ch03_html.dart
document.body.children.add(elem2);

Recall that elements are just a kind of node. You can find all the children of a node using the nodes property of Node, which returns a List<Node>. Once you have this list, you can use the usual List methods and operators to manipulate the children of the node.

To add a node as the last child of its parent, use the List add() method:

lang-dart
ch03_html/ch03_html.dart
// Find the parent by ID, and add elem as its last child.
query('#inputs').nodes.add(elem);

To replace a node, use the Node replaceWith() method:

lang-dart
ch03_html/ch03_html.dart
// Find a node by ID, and replace it in the DOM.
query('#status').replaceWith(elem);

To remove a node, use the Node remove() method:

lang-dart
ch03_html/ch03_html.dart
// Find a node by ID, and remove it from the DOM.
query('#expendable').remove();

CSS, or cascading style sheets, is used to define the presentation styles of DOM elements. You can change the appearance of an element by attaching ID and class attributes to it.

Each element has a classes field, which is a list. Add and remove CSS classes simply by adding and removing strings from this collection. For example, the following sample adds the warning class to an element:

lang-dart
ch03_html/ch03_html.dart
var element = query('#message');
element.classes.add('warning');

It’s often very efficient to find an element by ID. You can dynamically set an element ID with the id property:

lang-dart
ch03_html/ch03_html.dart
var message = new DivElement();
message.id = 'message2';
message.text = 'Please subscribe to the Dart mailing list.';

You can reduce the redundant text in this example by using method cascades:

lang-dart
ch03_html/ch03_html.dart
var message = new DivElement()
    ..id = 'message2'
    ..text = 'Please subscribe to the Dart mailing list.';

While using IDs and classes to associate an element with a set of styles is best practice, sometimes you want to attach a specific style directly to the element:

lang-dart
ch03_html/ch03_html.dart
message.style
    ..fontWeight = 'bold'
    ..fontSize = '3em';

To respond to external events such as clicks, changes of focus, and selections, add an event listener. You can add an event listener to any element on the page. Event dispatch and propagation is a complicated subject; research the details if you’re new to web programming.

Add an event handler using element.onEvent.listen(function), where Event is the event name and function is the event handler.

For example, here’s how you can handle clicks on a button:

lang-dart
ch03_html/ch03_html.dart
// Find a button by ID and add an event handler.
query('#submitInfo').onClick.listen((e) {
  // When the button is clicked, it runs this code.
  submitData();
});

Events can propagate up and down through the DOM tree. To discover which element originally fired the event, use e.target:

lang-dart
ch03_html/ch03_html.dart
document.body.onClick.listen((e) {
  var clickedElem = e.target;
  print('You clicked the ${clickedElem.id} element.');
});

To see all the events for which you can register an event listener, consult the API docs for ElementEvents and its subclasses. Some common events include:

The HttpRequest static method getString() is an easy way to get data from a web server. Use then() after getString() to specify the function that handles the string data.

lang-dart
ch03_html/ch03_2_html.dart
import 'dart:html';
import 'dart:async';

// A JSON-formatted file in the same location as this page.
var uri = 'data.json';

main() {
  // Read a JSON file.
  HttpRequest.getString(uri).then(processString);
}

processString(String jsonText) {
  parseText(jsonText);
}

The function you specify (in the example, processString()) runs when the data at the specified URI is successfully retrieved. In this case, we are dynamically loading a JSON file. Information about the JSON API is in the section called “dart:json - Encoding and Decoding Objects”.

Add .catchError() after the call to .then() to specify an error handler:

lang-dart
ch03_html/ch03_2_html.dart
...
HttpRequest.getString(uri)
    .then(processString)
    .catchError(handleError);
...
handleError(error) {
  print('Uh oh, there was an error.');
  print(error.toString());
}

If you need access to the HttpRequest, not just the text data it retrieves, you can use the request() static method instead of getString(). Here’s an example of reading XML data:

lang-dart
ch03_html/ch03_2_html.dart
import 'dart:html';
import 'dart:async';

// An XML-formatted file in the same location as this page.
var xmlUri = 'data.xml';

main() {
  // Read an XML file.
  HttpRequest.request(uri)
      .then(processRequest)
      .catchError(handleError);
}

processRequest(HttpRequest request) {
  var xmlDoc = request.responseXml;
  try {
    var license = xmlDoc.query('license').text;
    print('License: $license');
  } catch(e) {
    print('$xmlUri doesn\'t have correct XML formatting.');
  }
}
...

You can also use the full API to handle more interesting cases. For example, you can set arbitrary headers.

The general flow for using the full API of HttpRequest is as follows:

For example:

lang-dart
tutorial/servers/web/client.dart
import 'dart:html';
...
var httpRequest = new HttpRequest();
httpRequest.open('POST', dataUrl);
httpRequest.onLoadEnd.listen((e) => loadEnd(httpRequest));
httpRequest.send(encodedData);

HttpRequest can send data to the server using the HTTP method POST. For example, you might want to dynamically submit data to a form handler. Sending JSON data to a RESTful web service is another common example.

Submitting data to a form handler requires you to provide name-value pairs as URI-encoded strings. (Information about the URI class is in the section called “URIs”.) You must also set the Content-type header to application/x-www-form-urlencode if you wish to send data to a form handler.

lang-dart
ch03/ch03/ch03_3_html/json-send-to-server.dart
import 'dart:html';

String encodeMap(Map data) {
  return data.keys.map((k) {
    return '${Uri.encodeComponent(k)}=${Uri.encodeComponent(data[k])}';
  }).join('&');
}

loadEnd(HttpRequest request) {
  if (request.status != 200) {
    print('Uh oh, there was an error of ${request.status}');
  } else {
    print('Data has been posted');
  }
}

main() {
  var dataUrl = '/registrations/create';
  var data = {'dart': 'fun', 'editor': 'productive'};
  var encodedData = encodeMap(data);

  var httpRequest = new HttpRequest();
  httpRequest.open('POST', dataUrl);
  httpRequest.setRequestHeader('Content-type', 
                               'application/x-www-form-urlencoded');
  httpRequest.onLoadEnd.listen((e) => loadEnd(httpRequest));
  httpRequest.send(encodedData);
}

To send string data on the WebSocket, use the send() method:

lang-dart
sendMessage(String data) {
  if (webSocket.readyState == WebSocket.OPEN) {
    webSocket.send(data);
  } else {
    throw 'WebSocket not connected, message $data not sent';
  }
}

To receive data on the WebSocket, register a listener for message events:

lang-dart
webSocket.onMessage.listen((MessageEvent e) {
  receivedMessage(e.data);
});

The message event handler receives a MessageEvent object. This object’s data field has the data from the server. Here’s an example of decoding a JSON string sent on a WebSocket, where the JSON string has two fields, “from” and “content”:

lang-dart
// Called from the message listener like this: receivedMessage(e.data)
receivedMessage(String data) {
  Map message = json.parse(data);
  if (message['from'] != null) {
    print('Message from ${message['from']}: ${message['content']}');
  }
}

WebSocketEvents defines the WebSocket events your app can handle: open, close, error, and (as shown above) message. Here’s an example of a method that creates a WebSocket object and handles message, open, close, and error events:

lang-dart
connectToWebSocket([int retrySeconds = 2]) {
  bool reconnectScheduled = false;
  webSocket = new WebSocket(url);
  
  scheduleReconnect() {
    print('web socket closed, retrying in $retrySeconds seconds');
    if (!reconnectScheduled) {
      new Timer(new Duration(seconds:retrySeconds),
        () => connectToWebSocket(retrySeconds*2));
    }
    reconnectScheduled = true;
  }
  
  webSocket.onOpen.listen((e) {
    print('Connected');
  });
  
  webSocket.onClose.listen((e) => scheduleReconnect());
  webSocket.onError.listen((e) => scheduleReconnect());
  
  webSocket.onMessage.listen((MessageEvent e) {
    _receivedEncodedMessage(e.data);
  });
}

For an example of using WebSockets, see Chapter 5, Walkthrough: Dart Chat.

Any top-level function or static method^[2] is a valid entry point for an isolate. The entry point should not expect arguments and should return void. It is illegal to use a function closure as an entry point to an isolate. Pass the entry point to spawnFunction().

lang-dart
import 'dart:isolate';

runInIsolate() {
  print('hello from an isolate!');
}

main() {
  spawnFunction(runInIsolate);

  // Note: incomplete.
  // Use a ReceivePort (details below) to keep the root isolate alive
  // long enough for runInIsolate() to perform its work.
}

We plan to support spawning an isolate from code at a URI.

Send a message to an isolate via a SendPort. The spawnFunction() method returns a handle to the newly created isolate’s SendPort.

To simply send a message, use send():

lang-dart
import 'dart:isolate';

echo() {
  // Receive messages here. (See the next section.)
}

main() {
  var sendPort = spawnFunction(echo);
  sendPort.send('Hello from main');

  // Note: incomplete.
  // Use a ReceivePort (details below) to keep the root isolate alive
  // long enough for echo() to perform its work.
}

In special circumstances (such as when using spawnFunction() inside the Dart VM), it is possible to send any type of object to an isolate.^[3] The object message is copied when sent.

Use a ReceivePort to receive messages sent to an isolate. Obtain a handle to the default ReceivePort from the top-level port property. You can also create new instances of ReceivePort, if you want to route messages to different ports and callbacks.

Handle an incoming message with a callback function passed to the receive() method:

lang-dart
import 'dart:isolate';
echo() {
  port.receive((msg, reply) {
    print('I received: $msg');
  });
}

main() {
  var sendPort = spawnFunction(echo);
  sendPort.send('Hello from main');

  // Note: incomplete.
  // Use a ReceivePort (details below) to keep the root isolate alive
  // long enough for echo() to perform its work.
}

Use the call() method on SendPort as a simple way to send a message and receive a reply. The call() method returns a Future for the reply.

lang-dart
import 'dart:isolate';

echo() {
  port.receive((msg, reply) {
    reply.send('I received: $msg');
  });
}

main() {
  var sendPort = spawnFunction(echo);
  sendPort.call('Hello from main').then((reply) {
    print(reply);    // I received: Hello from main
  });
}

Under the covers, the call() method creates and manages a SendPort and a ReceivePort, which are necessary for a call-and-response message exchange.

In the VM, an isolate continues to run as long as it has an open ReceivePort inside the isolate. If the main() function only starts other isolates, doing no work itself, you must keep the root isolate alive to keep the program alive.

To keep a root isolate alive, open a ReceivePort in the root isolate. When all the child isolates have finished their work, you can send a message to the root isolate to close its ReceivePort, thus stopping the program.

You can coordinate isolates with message passing, sending a message to inform the root isolate when a child isolate finishes. Here is an example:

lang-dart
import 'dart:isolate';

childIsolate() {
  port.receive((msg, replyTo) {
    print('doing some work');
    if (replyTo != null) replyTo.send('shutdown');
  });
}

main() {
  var sender = spawnFunction(childIsolate);
  var receiver = new ReceivePort();
  receiver.receive((msg, _) {
    if (msg == 'shutdown') {
      print('shutting down');
      receiver.close();
    }
  });
  sender.send('do work please', receiver.toSendPort());
}

In the above example, the child isolate runs to completion because the root isolate keeps a ReceivePort open. The root isolate creates a ReceivePort to wait for a shutdown message. The term shutdown is arbitrary; the ReceivePort simply needs to wait for some signal.

Once the root isolate receives a shutdown message, it closes the ReceivePort. With the ReceivePort closed and nothing else to do, the root isolate terminates, causing the app to exit.

When reading a text file, you can read the entire file contents with readAsString(). When the individual lines are important, you can use readAsLines(). In both cases, a Future object is returned that provides the contents of the file as one or more strings.

lang-dart
ch03/textRead.dart
import 'dart:io';

main() {
  var config = new File('config.txt');

  // Put the whole file in a single string.
  config.readAsString().then((String contents) {
    print('The entire file is ${contents.length} characters long');
  });

  // Put each line of the file into its own string.
  config.readAsLines().then((List<String> lines) {
    print('The entire file is ${lines.length} lines long');
  });
}

The following code reads an entire file as bytes into a list of ints. The call to readAsBytes() returns a Future, which provides the result when it’s available.

lang-dart
ch03/binaryRead.dart
import 'dart:io';

main() {
  var config = new File('config.txt');

  config.readAsBytes().then((List<int> contents) {
    print('The entire file is ${contents.length} bytes long');
  });
}

Errors are thrown as exceptions if you do not register an explicit handler. If you want to capture an error, you can register a catchError handler with the Future object:

lang-dart
ch03/fileErrors.dart
import 'dart:io';

main() {
  var config = new File('config.txt');
  config.readAsString().then((String contents) {
    print(contents);
  }).catchError((e) {
    print(e);
  });
}

Use a Stream to read a file, a little at a time. The listen() method specifies a handler to be called when data is available. When the Stream is finished reading the file, the onDone callback executes.

lang-dart
ch03/readFile.dart
import 'dart:io';
import 'dart:async';

main() {
  var config = new File('config.txt');
  Stream<List<int>> inputStream = config.openRead();

  inputStream
    .transform(new StringDecoder())
    .transform(new LineTransformer())
    .listen(
      (String line) { 
        print('Read ${line.length} bytes from stream');
      },
      onDone: () { print('file is now closed'); },
      onError: (e) { print(e.toString()); });
}

To decode from bytes into characters, wrap the stream with a StringDecoder. You can read the strings either as data becomes available or one line at a time.

You can use an IOSink to write data to a file. Use the File openWrite() method to declare a mode and get an IOSink that you can write to. The default mode, FileMode.WRITE, completely overwrites existing data in the file.

lang-dart
ch03/writeFile.dart
var logFile = new File('log.txt');
var sink = logFile.openWrite();
sink.write('FILE ACCESSED ${new DateTime.now()}\n');
sink.close();

To add to the end of the file, use the optional mode parameter to specify FileMode.APPEND:

lang-dart
ch03/writeFile.dart
var sink = logFile.openWrite(mode: FileMode.APPEND); 

To write binary data, use add(List<int> buffer).

Finding all files and subdirectories for a directory is an asynchronous operation. The list() method returns a Stream on which you can register handlers (using listen()) to be notified when a file or directory is encountered.

lang-dart
ch03/listFiles.dart
import 'dart:io';
import 'dart:async';

main() {
  var dir = new Directory('/tmp');
  var contentsStream = dir.list(recursive:true);
  contentsStream.listen(
    (FileSystemEntity f) {
      if (f is File) {
        print('Found file ${f.path}');
      } else if (f is Directory) {
        print('Found dir ${f.path}');
      }
    },
    onError: (e) { print(e.toString()); }
  );
}

The File and Directory classes contain other functionality, including but not limited to:

Refer to the API docs for File and Directory for a full list of methods.

Besides the APIs discussed in this section, the dart:io library also provides APIs for processes, sockets, and web sockets.

For more examples of using dart:io, see Chapter 5, Walkthrough: Dart Chat.

The HttpServer class provides the low-level functionality for building web servers. You can match request handlers, set headers, stream data, and more.

The following sample web server can return only simple text information. This server listens on port 8888 and address 127.0.0.1 (localhost), responding to requests for the path /languages/dart. All other requests are handled by the default request handler, which returns a response code of 404 (not found).

lang-dart
ch03/httpServer.dart
import 'dart:io';

main() {
  dartHandler(HttpRequest request) {
    print('New request');
    request.response.write('Dart is optionally typed');
    request.response.close();
  };

  HttpServer.bind('127.0.0.1', 8888).then((HttpServer server) {
    server.listen((request) { 
      print("got request");
      if (request.uri.path == '/languages/dart') {
        dartHandler(request);
      } else {
        request.response.write('Not found');
        request.response.statusCode = HttpStatus.NOT_FOUND;
        request.response.close();
      }
    });
  });
}

You can see a more comprehensive HTTP server in the section called “The Server’s Code”.

The HttpClient class helps you connect to HTTP resources from your Dart command-line or server-side application. You can set headers, use HTTP methods, and read and write data. The HttpClient class does not work in browser-based apps. When programming in the browser, use the HttpRequest class. Here’s an example of using HttpClient:

lang-dart
ch03/httpClient.dart
import 'dart:io';

main() {
  var url = Uri.parse('http://127.0.0.1:8888/languages/dart');
  var httpClient = new HttpClient();
  httpClient.getUrl(url)
    .then((HttpClientRequest request) {
      print('have request');
      return request.close();
    })
    .then((HttpClientResponse response) {
      print('have response');
      response.transform(new StringDecoder()).toList().then((data) {
        var body = data.join('');
        print(body);
        httpClient.close();
      });
    });
}