date_time_format 1.0.0+4

  • Readme
  • Changelog
  • Installing
  • 91

date_time_format #

pub package style: effective dart

A utility class for formatting Dart's DateTime object using standard date/time notation or as a relative time offset.

Updating to v1.0.0: The names and locations of many of the original constants have been changed to follow more consistent naming conventions and to be better organized. See the bottom of this README for notes on the updated constants if you were using any of those affected.

Usage #

import 'package:date_time_format/date_time_format.dart';

date_time_format exposes a utility class, [DateTimeFormat] that contains two methods: [format] and [relative], that format [DateTime] objects as defined by standard date/time notation or as relative to the current or a provided [DateTime], respectively.

See the Date/Time Notations section below for a complete list of supported formatting notations.

In addition to the formatting utilities, a variety of date/time notation formatting constants are pre-defined in the following classes: DateTimeFormats contains standard date/time formatting notations. DateFormats and TimeFormats contain common date-only and time-only formatting constants, respectively. Additional American and European date/time formatting constants can be found in the AmericanDateFormats, AmericanDateTimeFormats, EuropeanDateFormats, and EuropeanDateTimeFormats classes.

Standard Formatting #

[DateTimeFormat.format] defaults to the ISO8601 date/time format.

final dateTime = DateTime.now();

// 2019-10-15T19:42:05-08:00
print(DateTimeFormat.format(dateTime));

// October 15, 2019 7:42 pm
print(DateTimeFormat.format(dateTime, format: DateTimeFormats.american));

// 15/Oct/2019:19:42:05 -0700
print(DateTimeFormat.format(dateTime, format: DateTimeFormats.commonLogFormat));

// Tuesday, October 15, 2019
print(DateTimeFormat.format(dateTime, format: AmericanDateFormats.dayOfWeek));

// Tue, Oct 15, 19:42
print(DateTimeFormat.format(dateTime, format: 'D, M j, H:i'));

Relative Formatting #

By default, [DateTimeFormat.relative] returns the time offset rounded to the nearest whole unit of time.

Note: Weeks can be excluded as an interval of time by setting the [excludeWeeks] parameter to true, and will not be counted as a degree of time in regards to [levelOfPrecision].

// 5 minutes
print(DateTimeFormat.relative(dateTime.subtract(Duration(minutes: 5))));

// 3 hours
print(DateTimeFormat.relative(dateTime.subtract(Duration(hours: 2, minutes: 30))));

// 5 days
print(DateTimeFormat.relative(dateTime.subtract(Duration(days: 5, hours: 10))));

// 1 week
print(DateTimeFormat.relative(dateTime.subtract(Duration(days: 9))));

// 9 days
print(DateTimeFormat.relative(dateTime.subtract(Duration(days: 9)),
    excludeWeeks: true));

Abbreviating: #

The returned intervals of time can be abbreviated by setting the [abbr] parameter to true.

final timeOffset = dateTime.subtract(Duration(minutes: 5));

// 5 minutes
print(DateTimeFormat.relative(timeOffset));

// 5m
print(DateTimeFormat.relative(timeOffset, abbr: true));

To compare the provided [DateTime] to another [DateTime] object, the [relativeTo] parameter can be set.

final timeOffset1 = dateTime.subtract(Duration(minutes: 5));
final timeOffset2 = dateTime.add(Duration(minutes: 5));

// 5 minutes
print(DateTimeFormat.relative(timeOffset1);

// 10 minutes
print(DateTimeFormat.relative(timeOffset1, relativeTo: timeOffset2));

Level of Precision: #

The [levelOfPrecision] parameter sets the degrees of removal from the largest interval counted that will be included in the count. I.e. minutes are 1 degree removed from hours, and seconds are 2 degrees removed from hours but only 1 degree removed from minutes.

final timeOffset = dateTime.add(Duration(days: 3, hours: 6, minutes: 30, seconds: 15));

// 3 days
print(DateTimeFormat.relative(timeOffset));

// 3 days 7 hours
print(DateTimeFormat.relative(timeOffset, levelOfPrecision: 1));

// 3 days 6 hours 30 minutes
print(DateTimeFormat.relative(timeOffset, levelOfPrecision: 2));

// 3 days 6 hours 30 minutes 15 seconds
print(DateTimeFormat.relative(timeOffset, levelOfPrecision: 3));

Minimum & Maximum Units of Time: #

The minimum and maximum intervals to include in the count can be specified by the [minUnitOfTime] and [maxUnitOfTime] respectively. The largest possible interval of time being a year, and the smallest being a microsecond.

By default, the smallest unit of time returned is a second, to include milliseconds or microseconds the [minUnitOfTime] parameter must be set to [UnitOfTime.milliseconds]/ [UnitOfTime.microseconds]. Note: Milliseconds and microseconds may be returned slightly off from the expected values if the function takes longer to process than those intervals of time.

final timeOffset = dateTime.add(Duration(
    days: 762, hours: 6, minutes: 30, seconds: 15, milliseconds: 300, microseconds: 740));

// 2 years 1 month 2 days
print(DateTimeFormat.relative(timeOffset, levelOfPrecision: 3));

// 25 months 5 days 7 hours
print(DateTimeFormat.relative(timeOffset, levelOfPrecision: 3,
    maxUnitOfTime: UnitOfTime.month));

// 762 days 6 hours 30 minutes 15 seconds
print(DateTimeFormat.relative(timeOffset, levelOfPrecision: 3,
    maxUnitOfTime: UnitOfTime.day));

// 2 years 1 month 2 days 6 hours 30 minutes 15 seconds
print(DateTimeFormat.relative(timeOffset, levelOfPrecision: 8));

// 2 years 1 month 2 days 6 hours 30 minutes 15 seconds 301 milliseconds
print(DateTimeFormat.relative(timeOffset, levelOfPrecision: 8,
    minUnitOfTime: UnitOfTime.millisecond));

// 2 years 1 month 2 days 6 hours 30 minutes 15 seconds 300 milliseconds 740 microseconds
print(DateTimeFormat.relative(timeOffset, levelOfPrecision: 8,
    minUnitOfTime: UnitOfTime.microsecond));

// 2y 1m 2d 6h 30m 15s 300ms 740mu
print(DateTimeFormat.relative(timeOffset, levelOfPrecision: 8,
    minUnitOfTime: UnitOfTime.microsecond, abbr: true));

Rounding: #

Rounding, which is enabled by default, can be disabled by setting the [round] parameter to false, in which case any measure of time that isn't included in the smallest returned interval will be truncated.

final timeOffset = dateTime.subtract(Duration(hours: 6, minutes: 45));

// 7 hours
print(DateTimeFormat.relative(timeOffset));

// 6 hours
print(DateTimeFormat.relative(timeOffset, round: false));

Formatting After X Amount of Time: #

[formatAfter] can be set to a [Duration] of time to return a standard formatted date/time stamp, via the [DateTimeFormat.format] method, if the difference in time is greater than the duration specified.

By default, date/time stamps will be formatted to the [AmericanDateTimeStamp.abbrWithComma] constant. A different formatting notation can be provided via the [format] parameter.

final timeOffset = dateTime.subtract(Duration(days: 762, hours: 6, minutes: 30));

// 2 years
print(DateTimeFormat.relative(timeOffset));

// Apr 29, 2018 6:27 am
print(DateTimeFormat.relative(timeOffset, formatAfter: Duration(days: 365)));

// 6:27 am · Apr 29, 2018
print(DateTimeFormat.relative(timeOffset, formatAfter: Duration(days: 365),
    format: r'g:i a · M j, Y'));

Prepending & Appending Text: #

[prependIfBefore] and [appendIfAfter] can be used to conveniently prepend and/or append a [String] before or after the returned relative time offset if the formatted [DateTime] occurs before or after [relativeTo] (which defaults to DateTime.now()), respectively.

// 5 days ago
print(DateTimeFormat.relative(dateTime.subtract(Duration(days: 5)),
    prependIfBefore: 'In', appendIfAfter: 'ago'));

// In 5 days
print(DateTimeFormat.relative(dateTime.add(Duration(days: 5)),
    prependIfBefore: 'In', appendIfAfter: 'ago'));

Return X Below Minimum Unit of Time: #

The [ifNow] parameter can be set to return a value if the difference in time is less than [minUnitOfTime], otherwise, an empty string will be returned.

// Now
print(DateTimeFormat.relative(DateTime.now(), ifNow: 'Now'));

// 5 minutes
print(DateTimeFormat.relative(dateTime.subtract(Duration(minutes: 5)), ifNow: 'Now'));

// Now
print(DateTimeFormat.relative(dateTime.subtract(Duration(minutes: 5)), ifNow: 'Now',
    minUnitOfTime: UnitOfTime.hour));

Date/Time Notations #

[DateTimeFormat.format] and [DateTime.relative]'s format parameter supports the following standard date/time formatting notations:

d : Day of month (01 - 31)

j : Day of month, without leading 0s (1 - 31)

D : An abbreviated textual representation of a day (Mon - Sun)

l : A textual representation of a day (Monday - Sunday)

S : Suffix of a day (st, th, nd)

z : The day of the year (starting from 0)

F : A textual representation of a month (January - December)

M : An abbreviated textual representation of a month (Jan - Dec)

m : Numeric representation of a month (01 - 12)

n : Numeric representation of a month, without leading 0s (1 - 12)

Y : Full numeric representation of a year (e.g. 2019)

y : A two digit representation of a year (e.g. 19)

a : Ante meridiem and post meridiem, lowercase (am or pm)

A : Ante meridiem and post meridiem, uppercase (AM or PM)

g : 12-hour format of an hour, without leading 0s (1 - 12)

h : 12-hour format of an hour (01 - 12)

G : 24-hour format of an hour, without leading 0s (0 - 23)

H : 24-hour format of an hour (00 - 23)

i : Minutes (0 - 59)

s : Seconds (0 - 59)

v : Milliseconds (0 - 999)

u : Microseconds (0 - 999)

e : Timezone identifier (Returns [DateTime.timeZoneName], which is provided by the operating system and may be a name or abbreviation.)

O : Difference to Greenwich Time (GMT) in hours (±0000)

P : Difference to Greenwich Time (GMT) in hours with a colon (±00:00)

T : Timezone abbreviation (Identifies the Timezone from [DateTime.timeZoneName].)

c : ISO 8601 date (e.g. 2019-10-15T19:42:05-08:00)

r : RFC 2822 date (Tue, 15 Oct 2019 17:42:05 -0800)

U : Seconds since Unix Epoch

\ : Escape character

Updated Constants for v1.0.0 #

The following constants have been moved and/or renamed to names/locations shown to their right.

DateTimeFormats.americanAbbr24Hour => AmericanDateTimeFormats.abbr24HourWithComma

DateTimeFormats.americanAbbrDate => AmericanDateFormats.abbr

DateTimeFormats.americanAbbrDateAbbr => AmericanDateFormats.abbrAbbr

DateTimeFormats.americanAbbrExtended24Hour => AmericanDateTimeFormats.abbr24HourExtendedWithComma

DateTimeFormats.americanDate => AmericanDateFormats.standard

DateTimeFormats.americanDateAbbr => AmericanDateFormats.standardAbbr

DateTimeFormats.americanDayOfWeekAbbr => AmericanDateTimeFormats.abbrDayOfWeekWithComma

DateTimeFormats.americanDayOfWeekAbbr24Hour => AmericanDateTimeFormats.abbrDayOfWeek24HourWithComma

DateTimeFormats.americanExtended24Hour => DateTimeFormats.american24HourExtended

DateTimeFormats.dayOfWeek => AmericanDateFormats.dayOfWeekWithComma

DateTimeFormats.dayOfWeek12Hour => AmericanDateTimeFormats.dayOfWeekWithComma

DateTimeFormats.dayOfWeek12HourExtended => AmericanDateTimeFormats.dayOfWeekExtendedWithComma

DateTimeFormats.dayOfWeek24Hour => AmericanDateTimeFormats.dayOfWeek24HourWithComma

DateTimeFormats.dayOfWeek24HourExtended => AmericanDateTimeFormats.dayOfWeek24HourExtendedWithComma

DateTimeFormats.dayOfWeekAbbr => AmericanDateFormats.abbrDayOfWeekAbbrWithComma

DateTimeFormats.dayOfWeekAbbr12Hour => AmericanDateTimeFormats.abbrDayOfWeekAbbrWithComma

DateTimeFormats.dayOfWeekAbbr12HourExtended => AmericanDateTimeFormats.abbrDayOfWeekAbbrExtendedWithComma

DateTimeFormats.dayOfWeekAbbr24Hour => AmericanDateTimeFormats.abbrDayOfWeekAbbr24HourWithComma

DateTimeFormats.dayOfWeekAbbr24HourExtended => AmericanDateTimeFormats.abbrDayOfWeekAbbr24HourExtendedWithComma

DateTimeFormats.dayOfWeekAbbrShort => AmericanDateFormats.abbrDayOfWeekAbbrShortWithComma

DateTimeFormats.dayOfWeekAbbrShort12Hour => AmericanDateTimeFormats.abbrDayOfWeekAbbrShortWithComma

DateTimeFormats.dayOfWeekAbbrShort24Hour => AmericanDateTimeFormats.abbrDayOfWeekAbbrShort24HourWithComma

DateTimeFormats.dayOfWeekShort => AmericanDateFormats.dayOfWeekShortWithComma

DateTimeFormats.european12Hour => EuropeanDateTimeFormats.standard12Hour

DateTimeFormats.european12HourExtended => EuropeanDateTimeFormats.extended12Hour

DateTimeFormats.european24Hour => EuropeanDateTimeFormats.standard

DateTimeFormats.european24HourExtended => EuropeanDateTimeFormats.extended

DateTimeFormats.europeanAbbr12Hour => EuropeanDateTimeFormats.abbr12Hour

DateTimeFormats.europeanAbbr12HourExtended => EuropeanDateTimeFormats.abbr12HourExtended

DateTimeFormats.europeanAbbr24Hour => EuropeanDateTimeFormats.abbr

DateTimeFormats.europeanAbbr24HourExtended => EuropeanDateTimeFormats.abbrExtended

DateTimeFormats.europeanDateAbbr => EuropeanDateFormats.abbrAbbr

DateTimeFormats.time12Hour => TimeFormats.standard

DateTimeFormats.time12HourExtended => TimeFormats.withSeconds

DateTimeFormats.time24Hour => TimeFormats.standard24Hour

DateTimeFormats.time24HourExtended => TimeFormats.withSeconds24Hour

[1.0.0] - May 30, 2020 #

  • Added significantly more American and European date/time formatting constants, plus additional date-only and time-only formatting constants.

  • Split the pre-defined date/time formatting constants into more classes: [DateTimeFormats], [DateFormats], [TimeFormats], [AmericanDateFormats], [AmericanDateTimeFormats], [EuropeanDateFormats], and [EuropeanDateTimeFormats].

  • Added the [relative] method to [DateTimeFormat] to return relative time differences.

[0.1.1+1] - April 26, 2020 #

  • Added additional date/time notation constants to [DateTimeFormats].

[0.1.1] - April 24, 2020 #

  • Added a list of every date/time notation constant to [DateTimeFormats].

[0.1.0] - March 11, 2020 #

  • Initial release.

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  date_time_format: ^1.0.0+4

2. Install it

You can install packages from the command line:

with pub:


$ pub get

with Flutter:


$ flutter pub get

Alternatively, your editor might support pub get or flutter pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:date_time_format/date_time_format.dart';
  
Popularity:
Describes how popular the package is relative to other packages. [more]
87
Health:
Code health derived from static analysis. [more]
100
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
90
Overall:
Weighted score of the above. [more]
91
Learn more about scoring.

We analyzed this package on Jul 9, 2020, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.8.4
  • pana: 0.13.14

Maintenance suggestions

Maintain an example. (-10 points)

Create a short demo in the example/ directory to show how to use this package.

Common filename patterns include main.dart, example.dart, and date_time_format.dart. Packages with multiple examples should provide example/README.md.

For more information see the pub package layout conventions.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.1.0 <3.0.0
Dev dependencies
effective_dart ^1.2.1
test ^1.12.0