📆 Dateable

A Dart package to help you with managing dates easily. Can be used to store, format, convert, construct, parse and serialise dates. Calendar correctness is guaranteed by the usage of DateTime‘s system under the hood.

⚙️ Import

In your .dart files:

import 'package:dateable/dateable.dart';

⚗️ Usage

👷 Constructors

Variety of different constructors allows for great flexibility and interoperability with other types.

final date = Date(31, 12, 2019);
final date = Date.fromDateTime(DateTime(2019, 12, 31, 19, 1)); // Time of day is truncated
final date = Date.parseIso8601('2019-12-31T18:23:48.956871'); // Time of day is truncated
final date = Date.parse('31122019');
final date = Date.today();
final date = Date.yesterday();
final date = Date.tomorrow();

And a handy DateTime extension:

final date = DateTime(2019, 12, 31, 13, 26).toDate(); // Time of day is truncated

All of the above result in the same date object!

📅 Getters

There are 4 getters. Simple and easy.

final date = Date(11, 3, 2002);
print(date.day); // Prints 11
print(date.month); // Prints 3
print(date.year); // Prints 2002
print(date.weekday) // Prints 1, since it's a Monday

↔️ Conversion methods

Date allows for seamless and easy conversions to most commonly used representations!

final date = Date(11, 3, 2002);
final dateTime = date.toDateTime(); // Time of day is set to zeros
print(date.toIso8601()); // Prints 2002-03-11T00:00:00.000
print(date.toIso8601(includeTime: false)) // Prints 2002-03-11
print(date.toString()); // Prints 11032002

✅ Validation

You can validate your dates easily with the isValid static method.

Since the default Date constructor doesn’t throw on invalid input, and always tries to silently convert to a valid date instead (just like the DateTime constructor), you may want to perform the validation explicitly.

print(Date.isValid(day: 11, month: 3, year: 2002)); // Prints true
print(Date.isValid(day: 29, month: 2, year: 2021)); // Prints false
print(Date.isValid(day: 40, month: 50, year: -99999)); // Prints true

📊 Comparisions

Comparisions work just like in your well-known DateTime objects!

final earlier = Date(11, 3, 2002);
final later = Date(21, 9, 2004);
print(earlier.isBefore(later)); // True
print(later.isAfter(earlier)); // Also true

On top of this, there are also operators > (is after) , < (is before), <=, >= and ==.

Here comes another handy DateTime extension:

DateTime(2002, 3, 11, 14, 56, 28).isTheSameDate(Date(11, 3, 2002));

But if all you want is to check if your Date is nearby, here you are.

final date = Date(11, 3, 2002);
date.isToday();
date.isYesterday();
date.isTomorrow();

📰 Formatting

You can format your Dates to Strings both with top-level constants and with String literals:

yyyy - 4 digit year, i.e. 1997
yy - 2 digit year, i.e. 97
mm - 2 digit month, i.e. 03
dd - 2 digit day, i.e. 11

Both of the below options are correct:

Date(11, 3, 2002).format([dd, '-', mm, '-', yyyy])

Date(11, 3, 2002).format(['dd', '-', 'mm', 'yyyy'])

🔨 Modifiers

Last but not least, there is a set of useful modifiers. Every Date object is immutable by default, so each of them creates a new Date object.

date.addDays(2) == date + 2 // Always true
date.subtractDays(7) == date - 7 // Also always true

You can also use the idiomatic copyWith function.

date.copyWith(day: 21, month: 9);

Sorting an Iterable of Dates chronologically is even easier:

[Date(21, 9, 2004), Date(24, 12, 2006), Date(11, 3, 2002)].sort((a, b) => a.compareTo(b));

Now the list is [Date(11, 3, 2002), Date(21, 9, 2004), Date(24, 12, 2006)].

🐛 Contributing / bug reporting

Contributions and bug reports are welcome! Feel free to open an issue or create a pull request.

📖 License

This package is distributed under MIT license.