date_n_time 1.0.7 copy "date_n_time: ^1.0.7" to clipboard
date_n_time: ^1.0.7 copied to clipboard

Dart Package for working with Dates without Times and/or Zones.

date_n_time #

A dart package extending DateTime to ease date or time representation and calculation.

When only needing to work with dates and/or times, using dart's DateTime can be tricky.
That is because, unless specifically constructed using .utc(),
it will take the timezone of the system, meaning additions and subtractions of time
become subject to the rules of the timezone the application is running in.

This package is heavily inspired by Java's solution to this: java.time.
A delicate balance has been searched between dart's existing classes and new ones.

Features #

The library makes a distinction between two types of objects:

  • Temporal: A moment in time, such as a date.
  • TemporalAmount: An amount of time, such as "6 hours".

Main Temporal implementations:

Class Dart equivalent Description Example
LocalDate n/a Date-only, without Zone 2024-10-26
LocalTime n/a Time-only, without Zone 10:30
LocalDateTime n/a Date + Time, without Zone 2024-10-26 10:30
ZonedDateTime DateTime Date + Time + Zone, Interchangeable 2024-10-26 10:30Z

Main TemporalAmount implementations:

Class Dart equivalent Description Example
Period n/a Length in Years, Months and Days P1Y2M3D
TimeSpan Duration Length in Microseconds, Interchangeable 01:02:03.456

The curious case of "days" #

When wanting to add a couple of days to, for example, a ZonedDateTime,
you will find there are two equally valid ways to do so:

  • Add/Subtract days using Period(days: n)
  • Add/Subtract days using TimeSpan(days: n)

There is a subtle, but important difference between the two implementations.
The former tries to increase/decrease the day, without touching the time.
The latter however tries to increase/decrease the time by 24 hours per day.

Although adding a full day of hours may work fine in most cases,
it becomes tricky whenever a time-zone change occurs.
Suddenly, a "full" day is actually 23 or 25 hours of length, potentially causing unexpected behavior.

Be aware of this behavior when choosing your method of calculation.
This only affects Temporal object that store a time-zone (e.g. ZonedDateTime).

Getting started #

TODO: List prerequisites and provide or point to information on how to start using the package.

Usage #

See the /example folder.

Notes #

The native DateTime currently has no concept of time-zones other than utc and system.
As the purpose of this package is merely to expand on what already exists,
handling different time-zones other than those two is considered out-of-scope.

Additional information #

This is a hobby project. Support can not be guaranteed.
Feedback is welcome.

0
likes
160
points
182
downloads

Publisher

unverified uploader

Weekly Downloads

Dart Package for working with Dates without Times and/or Zones.

Repository (GitHub)
View/report issues

Documentation

API reference

License

BSD-3-Clause (license)

Dependencies

intl

More

Packages that depend on date_n_time