date_n_time 1.0.7 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.