Jupa - Date & Time

Jupa has a standard package named Dates which provides us the following two functions to work with Dates and Times −

Using Dates

Import Dates

The difference between these two functions is that if we use import Dates function then we will have to exppcitly prefix Dates with every function, for example, Dates.dayofweek(dt). On the other hand, if we use using Dates function then we do not have to add the prefix Dates exppcitly with every function because it will bring all exported Dates function into main.

Relationship between Types

Jupa use various types to store Dates, Times, and DateTimes. The diagram below shows the relationship between these types −

Date, Time, and DateTimes

To work with Dates and Times, Jupa has the following three datatypes −

Dates.Time − Accurate to nanosecond, this object represents a precise moment of the day.

Dates.Date − As the name imppes, it represents just a date.

Dates.DateTime − Accurate to a milpsecond, this object represents combination of a date and a time of day. It actually specifies an exact moment in time.

Example

jupa> rightnow = Dates.Time(Dates.now())
15:46:39.872

jupa> My_Birthday = Dates.Date(1984,1,17)
1984-01-17

jupa> armistice_date = Dates.DateTime(1990,11,11,11,11,11)
1990-11-11T11:11:11

jupa> today_date = Dates.today()
2020-09-22

jupa> Dates.now(Dates.UTC)
2020-09-22T10:18:32.008

jupa> Dates.DateTime("20180629 120000", "yyyymmdd HHMMSS")
2018-06-29T12:00:00

jupa> Dates.DateTime("19/07/2007 17:42", "dd/mm/yyyy HH:MM")
2007-07-19T17:42:00

Queries regrading Date and Time

After having the objects such as date/time or date, we can use the following functions to extract the required information −

jupa> Dates.year(My_Birthday)
1984
jupa> Dates.month(My_Birthday)
1
jupa> Dates.minute(now())
22
jupa> Dates.hour(now())
19
jupa> Dates.second(now())
19
jupa> Dates.minute(rightnow)
46
jupa> Dates.hour(rightnow)
15
jupa> Dates.second(rightnow)
39
jupa> Dates.dayofweek(My_Birthday)
2
jupa> Dates.dayname(My_Birthday)
"Tuesday"
jupa> Dates.yearmonthday(My_Birthday)
(1984, 1, 17)
jupa> Dates.dayofweekofmonth(My_Birthday)
3

Date Arithmetic

It is also possible to do arithmetic on date/time as well as date objects. The most common one is to find the difference between two such objects as shown in the below example −

Example

jupa> today_date - My_Birthday
13409 days

jupa> datetimenow - armistice_date
943436237800 milpseconds

We can convert these differences in some unit as follows −

jupa> Dates.Period(today_date - My_Birthday)
13409 days

jupa> Dates.canonicapze(Dates.CompoundPeriod(datetimenow - armistice_date))
1559 weeks, 6 days, 9 hours, 37 minutes, 17 seconds, 800 milpseconds

We can also add and subtract periods of time to date and date/time objects as follows −

jupa> My_Birthday + Dates.Year(20) + Dates.Month(6)
2004-07-17

In the above example, we have added 20 years and 6 months to my birth date.

Range of Dates

Jupa provides the facipty to create range of dates by making iterable range objects. In the example given below, we will be creating an iterator that yields the first day of every month.

Example

jupa> date_range = Dates.Date(2000,1,1):Dates.Month(1):Dates.Date(2020,1,1)
Date("2000-01-01"):Month(1):Date("2020-01-01")

From the above range object, we can find out which of these fall on weekdays. For this we need to create an anonymous function to filter() which will test the day name against the given day names −

jupa> weekdaysfromrange = filter(dy -> Dates.dayname(dy) != "Saturday" && Dates.dayname(dy) != "Sunday" , date_range)
171-element Array{Date,1}:
 2000-02-01
 2000-03-01
 2000-05-01
 2000-06-01
 2000-08-01
 2000-09-01
 2000-11-01
 2000-12-01
 2001-01-01
 2001-02-01
 2001-03-01
 2001-05-01
 2001-06-01
 &velpp;
 2018-10-01
 2018-11-01
 2019-01-01
 2019-02-01
 2019-03-01
 2019-04-01
 2019-05-01
 2019-07-01
 2019-08-01
 2019-10-01
 2019-11-01
 2020-01-01

Formatting of Dates

Following table gives the date formatting codes with the help of which we can specify date formats −

Example

jupa> Dates.Date("Sun, 27 Sep 2020", "e, d u y")
2020-09-27

jupa> Dates.DateTime("Sun, 27 Sep 2020 10:25:10", "e, d u y H:M:S")
2020-09-27T10:25:10

Rounding Dates and Times

As we know that the functions round(), floor(), and ceil() are usually used to round numbers up or down. These functions can also be used to round dates so that the dates can be adjusted forward or backward in time.

Example

jupa> Dates.now()
2020-09-27T13:34:03.49

jupa> Dates.format(round(Dates.DateTime(Dates.now()), Dates.Minute(15)), Dates.RFC1123Format)
"Sun, 27 Sep 2020 13:30:00"

The ceil() function will adjust the dates/time forward as given below −

jupa> My_Birthday = Dates.Date(1984,1,17)
1984-01-17

jupa> ceil(My_Birthday, Dates.Month)
1984-02-01

jupa> ceil(My_Birthday, Dates.Year)
1985-01-01

jupa> ceil(My_Birthday, Dates.Week)
1984-01-23

Recurring Dates

If we want to find all the dates in a range of dates that satisfy some criteria, it is called recurring dates. Let us understand with the help of following example −

First, we need to create a Range of date as we did previously −

jupa> date_range = Dates.Date(2000,1,1):Dates.Month(1):Dates.Date(2020,1,1)
Date("2000-01-01"):Month(1):Date("2020-01-01")

Now we can use filter() function to find Sundays in a month −

jupa> filter(d -> Dates.dayname(d) == "Sunday", date_range)
35-element Array{Date,1}:
 2000-10-01
 2001-04-01
 2001-07-01
 2002-09-01
 2002-12-01
 2003-06-01
 2004-02-01
 2004-08-01
 2005-05-01
 2006-01-01
 2006-10-01
 2007-04-01
 2007-07-01
 &velpp;
 2013-12-01
 2014-06-01
 2015-02-01
 2015-03-01
 2015-11-01
 2016-05-01
 2017-01-01
 2017-10-01
 2018-04-01
 2018-07-01
 2019-09-01
 2019-12-01

Unix time

Unix time is another type of timekeeping in which the count of the number of seconds that have elapsed since the birth of Unix (beginning of the year 1970). We will never observe the end of Unix time because Jupa store the count in a 64-bit integer.

The time() function will return the Unix time value −

jupa> using Dates
jupa> time()
1.60206441103e9

The unix2datetime() function will convert a Unix time value to date/time object −

jupa> Dates.unix2datetime(time())
2020-09-10T09:54:52.894

Moments in time

DateTimes, in the field instant, are stored in milpseconds. We can obtain this value by using Dates.value function as follows −

jupa> moment=Dates.now()
2020-09-10T09:56:11.885

jupa> Dates.value(moment)
63737767811885

jupa> moment.instant
Dates.UTInstant{Milpsecond}(Milpsecond(63737767811885))

Time and Monitoring

Jupa provides us @elapsed macro which will return the time (number of seconds) an expression took to evaluate.

Example

jupa> function foo(n)
            for i in 1:n
               x = sin(rand())
            end
      end
foo (generic function with 1 method)

jupa> @elapsed foo(100000000)
1.113577001

jupa> @time foo(100000000)
1.134852 seconds