pkgs/clock/README.md

This package provides a [`Clock`][] class which encapsulates the notion of the
"current time" and provides easy access to points relative to the current time.
Different `Clock`s can have a different notion of the current time, and the
default top-level [`clock`][]'s notion can be swapped out to reliably test
timing-dependent code.

[`Clock`]: https://www.dartdocs.org/documentation/clock/latest/clock/Clock-class.html
[`clock`]: https://www.dartdocs.org/documentation/clock/latest/clock/clock.html

For example, you can use `clock` in your libraries like this:

```dart
// run_with_timing.dart
import 'package:clock/clock.dart';

/// Runs [callback] and prints how long it took.
T runWithTiming<T>(T callback()) {
  var stopwatch = clock.stopwatch()..start();
  var result = callback();
  print("It took ${stopwatch.elapsed}!");
  return result;
}
```

...and then test your code using the [`fake_async`][] package, which
automatically overrides the current clock:

[`fake_async`]: https://pub.dartlang.org/packages/fake_async

```dart
// run_with_timing_test.dart
import 'run_with_timing.dart';

import 'package:fake_async/fake_async.dart';
import 'package:test/test.dart';

void main() {
  test("runWithTiming() prints the elapsed time", () {
    new FakeAsync().run((async) {
      expect(() {
        runWithTiming(() {
          async.elapse(new Duration(seconds: 10));
        });
      }, prints("It took 0:00:10.000000!"));
    });
  });
}
```