# date_time_format A utility class, and extension methods, for formatting Dart's DateTime object using standard date/time notation or as a relative time offset.

# Usage

``````import 'package:date_time_format/date_time_format.dart';
``````

date_time_format exposes 2 utility methods, `format` and `relative`, that are added to the DateTime class as extension methods or can be accessed via the DateTimeFormat utility class.

`format` and `relative` 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

Note: Each example below shows the extension method being utilized, and the utility method being used on the next line. Both methods will return the same output.

``````final dateTime = DateTime.now();

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

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

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

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

// Tue, Oct 15, 19:42
print(dateTime.format('D, M j, H:i'));
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.

``````// 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));
``````

`relative` can also be called as an extension method on DateTime.

``````final dateTime = DateTime.now().subtract(Duration(minutes: 5));

// 5 minutes
print(dateTime.relative());

// 5 minutes ago
print(dateTime.relative(appendIfAfter: 'ago'));

// 5 minutes
print(dateTime.relative(to: DateTime.now().subtract(Duration(minutes: 10))));

// In 5 minutes
print(dateTime.relative(
to: DateTime.now().subtract(Duration(minutes: 10)),
prependIfBefore: 'In'));
``````

All of the parameters detailed on the DateTimeFormat.relative are also provided on the `DateTime.relative` extension method.

### 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));

// 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.

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`.

``````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
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

## Libraries

date_time_format
Utilities for formatting Dart's DateTime object using standard date/time notation or as a relative time offset.
{"ft_lang_label":"__label__en","ft_lang_prob":0.5501199,"math_prob":0.88228786,"size":10431,"snap":"2021-31-2021-39","text_gpt3_token_len":2559,"char_repetition_ratio":0.22834948,"word_repetition_ratio":0.09615385,"special_character_ratio":0.2481066,"punctuation_ratio":0.21839081,"nsfw_num_words":0,"has_unicode_error":false,"math_prob_llama3":0.9812207,"pos_list":[0,1,2],"im_url_duplicate_count":[null,3,null],"WARC_HEADER":"{\"WARC-Type\":\"response\",\"WARC-Date\":\"2021-07-26T16:22:09Z\",\"WARC-Record-ID\":\"<urn:uuid:36f4257d-9c82-4923-8d83-f9ffc7525dd2>\",\"Content-Length\":\"20400\",\"Content-Type\":\"application/http; msgtype=response\",\"WARC-Warcinfo-ID\":\"<urn:uuid:b688ec31-7ae1-4c45-9506-4885d9415490>\",\"WARC-Concurrent-To\":\"<urn:uuid:061273c2-dfe4-4147-a463-d2de4e611fba>\",\"WARC-IP-Address\":\"216.239.32.21\",\"WARC-Target-URI\":\"https://pub.dev/documentation/date_time_format/latest/\",\"WARC-Payload-Digest\":\"sha1:P5COV2S2XDNMGLHCKFMIMLJIUDEOLMZD\",\"WARC-Block-Digest\":\"sha1:N5RXWLT47JVVS34X7U5TITHXPNEYV6XL\",\"WARC-Identified-Payload-Type\":\"text/html\",\"warc_filename\":\"/cc_download/warc_2021/CC-MAIN-2021-31/CC-MAIN-2021-31_segments_1627046152144.81_warc_CC-MAIN-20210726152107-20210726182107-00305.warc.gz\"}"}