Start with the docs improvement in utils
Ensure right docs in core
Fix typo
Bearimy is the library for handling dates and times with Janet programming language.
The internal storage is the so-called UNIX epoch or the number of seconds
from 1970-01-01 in the GMT timezone. Another data structure used internally
is the Janet struct akin to the return structure from the os/date
core
function call.
Functionality added by the library leans heavily on Janet's table prototypes.
The first core type provides means for representing a date. It has an
eponymous prototype. For creating this data, the utility function make-date
can convert its argument from table
or struct
, which has the structure
similar to the core Janet's date, number
with epoch seconds, and from
string
representation of ISO 8601 format (YYYY-MM-DD).
The prototype contains five methods for representing Date:
format
returns Date representation as a string in ISO 8601 format.epoch
returns the UNIX epoch seconds.str-week-day
returns a string with the name of the day in the week. An
optional format argument can have two values:
:short
makes method return default short representation of the weekday
name (Sun, Mon, etc.):long
makes the method return a long representation of the weekday name
(Sunday, Monday, etc.)str-month
returns a string with the name of the month. An optional format
argument can have two values:
:short
makes method return default short representation of the month
name (Jan, Feb, etc.):long
makes the method return a long representation of the month name
(Sunday, Monday, etc.)local
returns the Date corrected for the current timezone.The second core type provides means for representing date and time. It
has an eponymous prototype. For creating this type, the utility function
make-date-time
can convert its argument from table
, struct
, number
with epoch seconds and from string
representation based on ISO 8601 format
(YYYY-MM-DD hh:mm:ss). This prototype inherits from the Date prototype. It
contains the same methods with the one notable change to format
, which
returns a string with the time information and adds one more method,
http-format
, which returns the representation suitable for HTTP headers.
The third core type provides means for representing and working with the
time intervals. The eponymous prototype contains only the :duration
key in
seconds. For creating this type, the utility function make-interval
can
convert its argument from number
of seconds, set as :duration
and from
table
with the :duration
key. It also converts the struct
with the
:duration
key or :start
and :end
keys or with one or more of :years
,
:months
, :days
, :hours
, :minutes
or :seconds
keys. These the
function recomputes to seconds. The last type of argument for the function
is a string representation in the format "1h 20m", etc.
There are eight methods for this prototype:
format
returns the Interval formatted for the human consumption in the
hh:mm:ss
format.compare
compares the Interval with another one and returns the integer
similarly to Janet's compare
core function.add
adds another Interval to this Interval.sub
substracts another Interval from this Interval.in-years
returns the Interval as a float number of years.in-days
returns the Interval as a float number of days.in-hours
returns the Interval as a float number of hours.in-minutes
returns the Interval as a float number of minutes.The fourth core type provides means for working with the DateTime in
the Calendar manner. Its eponymous prototype inherits from the DateTime
prototype. The utility function make-calendar
uses the make-date-time
function internally for creating this type.
The prototype has five more functions on top of all the DateTime provides:
sooner
returns the new Calendar with DateTime set to earlier one by the
Interval argument.later
returns the new Calendar with DateTime set to later one by the
Interval argument.compare
compares the Calendar with another one and returns the integer
similarly to Janet's compare
core function.before?
returns true if the argument Calendar is before this one in time.after?
returns true if the argument Calendar is after this one in time.The last core type provides means for working with a period starting
with DateTime and lasting for Interval duration. The utility function
make-period
takes Calendar and Period arguments and uses make-calendar
and make-interval
functions internally for converting them.
The prototype has five methods:
later
is similar to Calendar's later
method but takes the Interval
into account.contains?
returns true if the DateTime argument is within the boundaries
of the Period.after?
is similar to Calendar's after?
method but takes the Interval
into account.start
returns the epoch seconds of the DateTime part of the Period.end
returns the epoch seconds of the DateTime plus the Interval duration
part of the Period.On top of the core types and their methods are convenience functions for working with them. First are formatting functions:
format-date
, format-date-time
, http-format-date-time
, format-interval
are simple wrapper around the respective make-*
functions and call to
format
method of the result.format-time
formates DateTime time part and returns it in hh:mm:ss
format.format-now
takes the current DateTime and returns it formated.format-today
takes the current Date and returns it formated.The second group of functions provides convenience for creating the Calendar from the number of respective time units in history or future:
days-ago
returns a new Calendar based on current DateTime or an optional
provided one, moved by argument days to the history.days-after
returns a new Calendar based on current DateTime or an optional
provided one, moved by argument days into the future.
yesterday
returns a new Calendar of yesterday's DateTime.weeks-ago
returns a new Calendar based on current DateTime or an optional
provided one, moved by argument weeks to the history.months-ago
returns a new Calendar based on current DateTime or an optional
provided one, moved by argument months; to the history.start-of-week
returns a new Calendar based on current DateTime or an
optional provided one, set to the first day of the week.current-week-start
returns a new Calendar set to the start of the
current week.
last-week-start
returns a new Calendar set to the start of the last week.start-of-month
returns a new Calendar based on current DateTime or an
optional provided one, set number of months in the history.current-month-start
returns a new Calendar set to the start of the
current month.last-month-start
returns a new Calendar set to the start of the last month.start-of-year
returns a new Calendar based on current DateTime or an
optional provided one, set number of years in the history.current-year-start
returns a new Calendar set to the start of the
current year.The last function, human
, represents the DateTime argument in the
human-readable format concerning the current DateTime (now, last month,
and so on).