Style changes
diff --git a/lib/clock.dart b/lib/clock.dart
index 4ee971a..7fd2520 100644
--- a/lib/clock.dart
+++ b/lib/clock.dart
@@ -15,32 +15,30 @@
import 'src/utils.dart';
/// Returns current time.
+@Deprecated("Pass around an instance of Clock instead.")
typedef DateTime TimeFunction();
/// Return current system time.
+@Deprecated("Use new DateTime.now() instead.")
DateTime systemTime() => new DateTime.now();
-/// Provides points in time relative to the current point in time, for example:
-/// now, 2 days ago, 4 weeks from now, etc.
+/// A class which encapsulates the notion of the "current time" and provides
+/// easy access to points relative to the current time.
///
/// This class is designed with testability in mind. The current point in time
-/// (or [now()]) is defined by a [TimeFunction]. By supplying your own time
-/// function or by using fixed clock (see constructors), you can control
-/// exactly what time a [Clock] returns and base your test expectations on
-/// that. See specific constructors for how to supply time functions.
+/// (or [now()]) is defined by a function that returns a [DateTime]. By
+/// supplying your own time function or using [new Clock.fixed], you can control
+/// exactly what time a [Clock] returns and base your test expectations on that.
class Clock {
- final TimeFunction _time;
+ /// The function that's called to determine this clock's notion of the current
+ /// time.
+ final DateTime Function() _time;
- /// Creates a clock based on the given [timeFunc].
- ///
- /// If [timeFunc] is not provided, creates [Clock] based on system clock.
- ///
- /// Custom [timeFunc] can be useful in unit-tests. For example, you might
- /// want to control what time it is now and set date and time expectations in
- /// your test cases.
- const Clock([TimeFunction timeFunc = systemTime]) : _time = timeFunc;
+ /// Creates a clock based on the given [currentTime], or on the system clock
+ /// by default.
+ const Clock([DateTime currentTime()]) : _time = currentTime ?? systemTime;
- /// Creates [Clock] that returns fixed [time] value. Useful in unit-tests.
+ /// Creates [Clock] that always considers the current time to be [time].
Clock.fixed(DateTime time) : _time = (() => time);
/// Returns current time.
@@ -52,9 +50,9 @@
/// Returns the point in time [Duration] amount of time from now.
DateTime fromNowBy(Duration duration) => now().add(duration);
- /// Returns the point in time that's given amount of time ago. The
- /// amount of time is the sum of individual parts. Parts are compatible with
- /// ones defined in [Duration].
+ /// Returns the point in time that's given amount of time ago.
+ ///
+ /// The amount of time is the sum of the individual parts.
DateTime ago(
{int days: 0,
int hours: 0,
@@ -70,9 +68,9 @@
milliseconds: milliseconds,
microseconds: microseconds));
- /// Returns the point in time that's given amount of time from now. The
- /// amount of time is the sum of individual parts. Parts are compatible with
- /// ones defined in [Duration].
+ /// Returns the point in time that's given amount of time from now.
+ ///
+ /// The amount of time is the sum of the individual parts.
DateTime fromNow(
{int days: 0,
int hours: 0,
@@ -88,17 +86,19 @@
milliseconds: milliseconds,
microseconds: microseconds));
- /// Return the point in time [micros] microseconds ago.
- DateTime microsAgo(int micros) => ago(microseconds: micros);
+ /// Return the point in time [microseconds] ago.
+ DateTime microsAgo(int microseconds) => ago(microseconds: microseconds);
- /// Return the point in time [micros] microseconds from now.
- DateTime microsFromNow(int micros) => fromNow(microseconds: micros);
+ /// Return the point in time [microseconds] from now.
+ DateTime microsFromNow(int microseconds) =>
+ fromNow(microseconds: microseconds);
- /// Return the point in time [millis] milliseconds ago.
- DateTime millisAgo(int millis) => ago(milliseconds: millis);
+ /// Return the point in time [milliseconds] ago.
+ DateTime millisAgo(int milliseconds) => ago(milliseconds: milliseconds);
- /// Return the point in time [millis] milliseconds from now.
- DateTime millisFromNow(int millis) => fromNow(milliseconds: millis);
+ /// Return the point in time [milliseconds] from now.
+ DateTime millisFromNow(int milliseconds) =>
+ fromNow(milliseconds: milliseconds);
/// Return the point in time [seconds] ago.
DateTime secondsAgo(int seconds) => ago(seconds: seconds);
@@ -131,34 +131,46 @@
DateTime weeksFromNow(int weeks) => fromNow(days: 7 * weeks);
/// Return the point in time [months] ago on the same date.
+ ///
+ /// If the current day of the month isn't valid in the new month, the nearest
+ /// valid day in the new month will be used.
DateTime monthsAgo(int months) {
var time = now();
- var m = (time.month - months - 1) % 12 + 1;
- var y = time.year - (months + 12 - time.month) ~/ 12;
- var d = clampDayOfMonth(year: y, month: m, day: time.day);
- return new DateTime(
- y, m, d, time.hour, time.minute, time.second, time.millisecond);
- }
-
- /// Return the point in time [months] from now on the same date.
- DateTime monthsFromNow(int months) {
- var time = now();
- var m = (time.month + months - 1) % 12 + 1;
- var y = time.year + (months + time.month - 1) ~/ 12;
- var d = clampDayOfMonth(year: y, month: m, day: time.day);
- return new DateTime(
- y, m, d, time.hour, time.minute, time.second, time.millisecond);
- }
-
- /// Return the point in time [years] ago on the same date.
- DateTime yearsAgo(int years) {
- var time = now();
- var y = time.year - years;
- var d = clampDayOfMonth(year: y, month: time.month, day: time.day);
- return new DateTime(y, time.month, d, time.hour, time.minute, time.second,
+ var month = (time.month - months - 1) % 12 + 1;
+ var year = time.year - (months + 12 - time.month) ~/ 12;
+ var day = clampDayOfMonth(year: year, month: month, day: time.day);
+ return new DateTime(year, month, day, time.hour, time.minute, time.second,
time.millisecond);
}
+ /// Return the point in time [months] from now on the same date.
+ ///
+ /// If the current day of the month isn't valid in the new month, the nearest
+ /// valid day in the new month will be used.
+ DateTime monthsFromNow(int months) {
+ var time = now();
+ var month = (time.month + months - 1) % 12 + 1;
+ var year = time.year + (months + time.month - 1) ~/ 12;
+ var day = clampDayOfMonth(year: year, month: month, day: time.day);
+ return new DateTime(year, month, day, time.hour, time.minute, time.second,
+ time.millisecond);
+ }
+
+ /// Return the point in time [years] ago on the same date.
+ ///
+ /// If the current day of the month isn't valid in the new year, the nearest
+ /// valid day in the original month will be used.
+ DateTime yearsAgo(int years) {
+ var time = now();
+ var year = time.year - years;
+ var day = clampDayOfMonth(year: year, month: time.month, day: time.day);
+ return new DateTime(year, time.month, day, time.hour, time.minute,
+ time.second, time.millisecond);
+ }
+
/// Return the point in time [years] from now on the same date.
+ ///
+ /// If the current day of the month isn't valid in the new year, the nearest
+ /// valid day in the original month will be used.
DateTime yearsFromNow(int years) => yearsAgo(-years);
}
diff --git a/lib/src/utils.dart b/lib/src/utils.dart
index c4f11d0..48fd0be 100644
--- a/lib/src/utils.dart
+++ b/lib/src/utils.dart
@@ -18,8 +18,10 @@
import 'package:meta/meta.dart';
-/// Days in a month. This array uses 1-based month numbers, i.e. January is
-/// the 1-st element in the array, not the 0-th.
+/// The number of days in each month.
+///
+/// This array uses 1-based month numbers, i.e. January is the 1-st element in
+/// the array, not the 0-th.
const _daysInMonth = const [0, 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
/// Returns the number of days in the specified month.
@@ -38,7 +40,7 @@
/// This function assumes the use of the Gregorian calendar or the proleptic
/// Gregorian calendar.
bool isLeapYear(int year) =>
- (year % 4 == 0) && ((year % 100 != 0) || (year % 400 == 0));
+ year % 4 == 0 && (year % 100 != 0 || year % 400 == 0);
/// Takes a [date] that may be outside the allowed range of dates for a given
/// [month] in a given [year] and returns the closest date that is within the
@@ -54,9 +56,6 @@
/// date value to fit within the month. For example, jumping from March 31 one
/// month back takes us to February 28 (or 29 during a leap year), as February
/// doesn't have 31-st date.
-int clampDayOfMonth({
- @required int year,
- @required int month,
- @required int day,
-}) =>
- day.clamp(1, daysInMonth(year, month));
\ No newline at end of file
+int clampDayOfMonth(
+ {@required int year, @required int month, @required int day}) =>
+ day.clamp(1, daysInMonth(year, month));
diff --git a/test/clock_test.dart b/test/clock_test.dart
index 7048c47..633cdb9 100644
--- a/test/clock_test.dart
+++ b/test/clock_test.dart
@@ -16,211 +16,205 @@
import 'package:test/test.dart';
-Clock from(int y, int m, int d) => new Clock.fixed(new DateTime(y, m, d));
+/// A utility function for tersely constructing a [DateTime] with no time
+/// component.
+DateTime _date(int year, [int month, int day]) =>
+ new DateTime(year, month ?? 1, day ?? 1);
-expectDate(DateTime date, int y, [int m = 1, int d = 1]) {
- expect(date, new DateTime(y, m, d));
-}
+/// Return a clock that always returns a date with the given [year], [month],
+/// and [day].
+Clock _fixed(int year, [int month, int day]) =>
+ new Clock.fixed(_date(year, month, day));
main() {
- group('clock', () {
- Clock subject;
+ Clock clock;
+ setUp(() {
+ clock = new Clock.fixed(_date(2013));
+ });
- setUp(() {
- subject = new Clock.fixed(new DateTime(2013));
- });
+ test('should return a non-null value from system clock', () {
+ expect(const Clock().now(), isNotNull);
+ });
- test('should return a non-null value from system clock', () {
- expect(const Clock().now(), isNotNull);
- });
+ // This test may be flaky on certain systems. I ran it over 10 million
+ // cycles on my machine without any failures, but that's no guarantee.
+ test('should be close enough to system clock', () {
+ // At 10ms the test doesn't seem to be flaky.
+ var epsilon = 10;
+ expect(
+ new DateTime.now().difference(new Clock().now()).inMilliseconds.abs(),
+ lessThan(epsilon));
+ expect(
+ new DateTime.now().difference(const Clock().now()).inMilliseconds.abs(),
+ lessThan(epsilon));
+ });
- // This test may be flaky on certain systems. I ran it over 10 million
- // cycles on my machine without any failures, but that's no guarantee.
- test('should be close enough to system clock', () {
- // At 10ms the test doesn't seem to be flaky.
- var epsilon = 10;
- expect(
- new DateTime.now().difference(new Clock().now()).inMilliseconds.abs(),
- lessThan(epsilon));
- expect(
- new DateTime.now()
- .difference(const Clock().now())
- .inMilliseconds
- .abs(),
- lessThan(epsilon));
- });
+ test('should return time provided by a custom function', () {
+ var time = _date(2013);
+ var fixedClock = new Clock(() => time);
+ expect(fixedClock.now(), _date(2013));
- test('should return time provided by custom TimeFunction', () {
- var time = new DateTime(2013);
- var fixedClock = new Clock(() => time);
- expect(fixedClock.now(), new DateTime(2013));
+ time = _date(2014);
+ expect(fixedClock.now(), _date(2014));
+ });
- time = new DateTime(2014);
- expect(fixedClock.now(), new DateTime(2014));
- });
+ test('should return fixed time', () {
+ expect(new Clock.fixed(_date(2013)).now(), _date(2013));
+ });
- test('should return fixed time', () {
- expect(new Clock.fixed(new DateTime(2013)).now(), new DateTime(2013));
- });
+ test('should return time Duration ago', () {
+ expect(clock.agoBy(const Duration(days: 366)), _date(2012));
+ });
- test('should return time Duration ago', () {
- expect(subject.agoBy(const Duration(days: 366)), new DateTime(2012));
- });
+ test('should return time Duration from now', () {
+ expect(clock.fromNowBy(const Duration(days: 365)), _date(2014));
+ });
- test('should return time Duration from now', () {
- expect(subject.fromNowBy(const Duration(days: 365)), new DateTime(2014));
- });
+ test('should return time parts ago', () {
+ expect(
+ clock.ago(
+ days: 1,
+ hours: 1,
+ minutes: 1,
+ seconds: 1,
+ milliseconds: 1,
+ microseconds: 1000),
+ new DateTime(2012, 12, 30, 22, 58, 58, 998));
+ });
- test('should return time parts ago', () {
- expect(
- subject.ago(
- days: 1,
- hours: 1,
- minutes: 1,
- seconds: 1,
- milliseconds: 1,
- microseconds: 1000),
- new DateTime(2012, 12, 30, 22, 58, 58, 998));
- });
+ test('should return time parts from now', () {
+ expect(
+ clock.fromNow(
+ days: 1,
+ hours: 1,
+ minutes: 1,
+ seconds: 1,
+ milliseconds: 1,
+ microseconds: 1000),
+ new DateTime(2013, 1, 2, 1, 1, 1, 2));
+ });
- test('should return time parts from now', () {
- expect(
- subject.fromNow(
- days: 1,
- hours: 1,
- minutes: 1,
- seconds: 1,
- milliseconds: 1,
- microseconds: 1000),
- new DateTime(2013, 1, 2, 1, 1, 1, 2));
- });
+ test('should return time micros ago', () {
+ expect(clock.microsAgo(1000), new DateTime(2012, 12, 31, 23, 59, 59, 999));
+ });
- test('should return time micros ago', () {
- expect(
- subject.microsAgo(1000), new DateTime(2012, 12, 31, 23, 59, 59, 999));
- });
+ test('should return time micros from now', () {
+ expect(clock.microsFromNow(1000), new DateTime(2013, 1, 1, 0, 0, 0, 1));
+ });
- test('should return time micros from now', () {
- expect(subject.microsFromNow(1000), new DateTime(2013, 1, 1, 0, 0, 0, 1));
- });
+ test('should return time millis ago', () {
+ expect(clock.millisAgo(1000), new DateTime(2012, 12, 31, 23, 59, 59, 000));
+ });
- test('should return time millis ago', () {
- expect(
- subject.millisAgo(1000), new DateTime(2012, 12, 31, 23, 59, 59, 000));
- });
+ test('should return time millis from now', () {
+ expect(clock.millisFromNow(3), new DateTime(2013, 1, 1, 0, 0, 0, 3));
+ });
- test('should return time millis from now', () {
- expect(subject.millisFromNow(3), new DateTime(2013, 1, 1, 0, 0, 0, 3));
- });
+ test('should return time seconds ago', () {
+ expect(clock.secondsAgo(10), new DateTime(2012, 12, 31, 23, 59, 50, 000));
+ });
- test('should return time seconds ago', () {
- expect(
- subject.secondsAgo(10), new DateTime(2012, 12, 31, 23, 59, 50, 000));
- });
+ test('should return time seconds from now', () {
+ expect(clock.secondsFromNow(3), new DateTime(2013, 1, 1, 0, 0, 3, 0));
+ });
- test('should return time seconds from now', () {
- expect(subject.secondsFromNow(3), new DateTime(2013, 1, 1, 0, 0, 3, 0));
- });
+ test('should return time minutes ago', () {
+ expect(clock.minutesAgo(10), new DateTime(2012, 12, 31, 23, 50, 0, 000));
+ });
- test('should return time minutes ago', () {
- expect(
- subject.minutesAgo(10), new DateTime(2012, 12, 31, 23, 50, 0, 000));
- });
+ test('should return time minutes from now', () {
+ expect(clock.minutesFromNow(3), new DateTime(2013, 1, 1, 0, 3, 0, 0));
+ });
- test('should return time minutes from now', () {
- expect(subject.minutesFromNow(3), new DateTime(2013, 1, 1, 0, 3, 0, 0));
- });
+ test('should return time hours ago', () {
+ expect(clock.hoursAgo(10), new DateTime(2012, 12, 31, 14, 0, 0, 000));
+ });
- test('should return time hours ago', () {
- expect(subject.hoursAgo(10), new DateTime(2012, 12, 31, 14, 0, 0, 000));
- });
+ test('should return time hours from now', () {
+ expect(clock.hoursFromNow(3), new DateTime(2013, 1, 1, 3, 0, 0, 0));
+ });
- test('should return time hours from now', () {
- expect(subject.hoursFromNow(3), new DateTime(2013, 1, 1, 3, 0, 0, 0));
- });
+ test('should return time days ago', () {
+ expect(clock.daysAgo(10), _date(2012, 12, 22));
+ });
- test('should return time days ago', () {
- expectDate(subject.daysAgo(10), 2012, 12, 22);
- });
+ test('should return time days from now', () {
+ expect(clock.daysFromNow(3), _date(2013, 1, 4));
+ });
- test('should return time days from now', () {
- expectDate(subject.daysFromNow(3), 2013, 1, 4);
- });
+ test('should return time months ago on the same date', () {
+ expect(clock.monthsAgo(1), _date(2012, 12, 1));
+ expect(clock.monthsAgo(2), _date(2012, 11, 1));
+ expect(clock.monthsAgo(3), _date(2012, 10, 1));
+ expect(clock.monthsAgo(4), _date(2012, 9, 1));
+ });
- test('should return time months ago on the same date', () {
- expectDate(subject.monthsAgo(1), 2012, 12, 1);
- expectDate(subject.monthsAgo(2), 2012, 11, 1);
- expectDate(subject.monthsAgo(3), 2012, 10, 1);
- expectDate(subject.monthsAgo(4), 2012, 9, 1);
- });
+ test('should return time months from now on the same date', () {
+ expect(clock.monthsFromNow(1), _date(2013, 2, 1));
+ expect(clock.monthsFromNow(2), _date(2013, 3, 1));
+ expect(clock.monthsFromNow(3), _date(2013, 4, 1));
+ expect(clock.monthsFromNow(4), _date(2013, 5, 1));
+ });
- test('should return time months from now on the same date', () {
- expectDate(subject.monthsFromNow(1), 2013, 2, 1);
- expectDate(subject.monthsFromNow(2), 2013, 3, 1);
- expectDate(subject.monthsFromNow(3), 2013, 4, 1);
- expectDate(subject.monthsFromNow(4), 2013, 5, 1);
- });
+ test('should go from 2013-05-31 to 2012-11-30', () {
+ expect(_fixed(2013, 5, 31).monthsAgo(6), _date(2012, 11, 30));
+ });
- test('should go from 2013-05-31 to 2012-11-30', () {
- expectDate(from(2013, 5, 31).monthsAgo(6), 2012, 11, 30);
- });
+ test('should go from 2013-03-31 to 2013-02-28 (common year)', () {
+ expect(_fixed(2013, 3, 31).monthsAgo(1), _date(2013, 2, 28));
+ });
- test('should go from 2013-03-31 to 2013-02-28 (common year)', () {
- expectDate(from(2013, 3, 31).monthsAgo(1), 2013, 2, 28);
- });
+ test('should go from 2013-05-31 to 2013-02-28 (common year)', () {
+ expect(_fixed(2013, 5, 31).monthsAgo(3), _date(2013, 2, 28));
+ });
- test('should go from 2013-05-31 to 2013-02-28 (common year)', () {
- expectDate(from(2013, 5, 31).monthsAgo(3), 2013, 2, 28);
- });
+ test('should go from 2004-03-31 to 2004-02-29 (leap year)', () {
+ expect(_fixed(2004, 3, 31).monthsAgo(1), _date(2004, 2, 29));
+ });
- test('should go from 2004-03-31 to 2004-02-29 (leap year)', () {
- expectDate(from(2004, 3, 31).monthsAgo(1), 2004, 2, 29);
- });
+ test('should go from 2013-03-31 to 2013-06-30', () {
+ expect(_fixed(2013, 3, 31).monthsFromNow(3), _date(2013, 6, 30));
+ });
- test('should go from 2013-03-31 to 2013-06-30', () {
- expectDate(from(2013, 3, 31).monthsFromNow(3), 2013, 6, 30);
- });
+ test('should go from 2003-12-31 to 2004-02-29 (common to leap)', () {
+ expect(_fixed(2003, 12, 31).monthsFromNow(2), _date(2004, 2, 29));
+ });
- test('should go from 2003-12-31 to 2004-02-29 (common to leap)', () {
- expectDate(from(2003, 12, 31).monthsFromNow(2), 2004, 2, 29);
- });
+ test('should go from 2004-02-29 to 2003-02-28 by year', () {
+ expect(_fixed(2004, 2, 29).yearsAgo(1), _date(2003, 2, 28));
+ });
- test('should go from 2004-02-29 to 2003-02-28 by year', () {
- expectDate(from(2004, 2, 29).yearsAgo(1), 2003, 2, 28);
- });
+ test('should go from 2004-02-29 to 2003-02-28 by month', () {
+ expect(_fixed(2004, 2, 29).monthsAgo(12), _date(2003, 2, 28));
+ });
- test('should go from 2004-02-29 to 2003-02-28 by month', () {
- expectDate(from(2004, 2, 29).monthsAgo(12), 2003, 2, 28);
- });
+ test('should go from 2004-02-29 to 2005-02-28 by year', () {
+ expect(_fixed(2004, 2, 29).yearsFromNow(1), _date(2005, 2, 28));
+ });
- test('should go from 2004-02-29 to 2005-02-28 by year', () {
- expectDate(from(2004, 2, 29).yearsFromNow(1), 2005, 2, 28);
- });
+ test('should go from 2004-02-29 to 2005-02-28 by month', () {
+ expect(_fixed(2004, 2, 29).monthsFromNow(12), _date(2005, 2, 28));
+ });
- test('should go from 2004-02-29 to 2005-02-28 by month', () {
- expectDate(from(2004, 2, 29).monthsFromNow(12), 2005, 2, 28);
- });
+ test('should return time years ago on the same date', () {
+ expect(clock.yearsAgo(1), _date(2012, 1, 1)); // leap year
+ expect(clock.yearsAgo(2), _date(2011, 1, 1));
+ expect(clock.yearsAgo(3), _date(2010, 1, 1));
+ expect(clock.yearsAgo(4), _date(2009, 1, 1));
+ expect(clock.yearsAgo(5), _date(2008, 1, 1)); // leap year
+ expect(clock.yearsAgo(6), _date(2007, 1, 1));
+ expect(clock.yearsAgo(30), _date(1983, 1, 1));
+ expect(clock.yearsAgo(2013), _date(0, 1, 1));
+ });
- test('should return time years ago on the same date', () {
- expectDate(subject.yearsAgo(1), 2012, 1, 1); // leap year
- expectDate(subject.yearsAgo(2), 2011, 1, 1);
- expectDate(subject.yearsAgo(3), 2010, 1, 1);
- expectDate(subject.yearsAgo(4), 2009, 1, 1);
- expectDate(subject.yearsAgo(5), 2008, 1, 1); // leap year
- expectDate(subject.yearsAgo(6), 2007, 1, 1);
- expectDate(subject.yearsAgo(30), 1983, 1, 1);
- expectDate(subject.yearsAgo(2013), 0, 1, 1);
- });
-
- test('should return time years from now on the same date', () {
- expectDate(subject.yearsFromNow(1), 2014, 1, 1);
- expectDate(subject.yearsFromNow(2), 2015, 1, 1);
- expectDate(subject.yearsFromNow(3), 2016, 1, 1);
- expectDate(subject.yearsFromNow(4), 2017, 1, 1);
- expectDate(subject.yearsFromNow(5), 2018, 1, 1);
- expectDate(subject.yearsFromNow(6), 2019, 1, 1);
- expectDate(subject.yearsFromNow(30), 2043, 1, 1);
- expectDate(subject.yearsFromNow(1000), 3013, 1, 1);
- });
+ test('should return time years from now on the same date', () {
+ expect(clock.yearsFromNow(1), _date(2014, 1, 1));
+ expect(clock.yearsFromNow(2), _date(2015, 1, 1));
+ expect(clock.yearsFromNow(3), _date(2016, 1, 1));
+ expect(clock.yearsFromNow(4), _date(2017, 1, 1));
+ expect(clock.yearsFromNow(5), _date(2018, 1, 1));
+ expect(clock.yearsFromNow(6), _date(2019, 1, 1));
+ expect(clock.yearsFromNow(30), _date(2043, 1, 1));
+ expect(clock.yearsFromNow(1000), _date(3013, 1, 1));
});
}
