Calendar time package for Julia
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
src
test
LICENSE
README.md
REQUIRE

README.md

Calendar.jl: Calendar time for Julia

Calendar.jl is a simple, timezone-aware, localized calendar date & time module for Julia. The design is inspired by Hadley Wickham's lubridate package for R and the ISO 8601 standard.

Installation

To install the package:

julia> Pkg.add("Calendar")

Then, to load into your session:

julia> using Calendar

Calendar.jl requires the International Components for Unicode (ICU) libraries be installed on your system. It comes preinstalled on OS X and most Linux desktop distributions, but if not:

  • Arch: pacman -S icu
  • Fedora: yum install icu
  • Ubuntu: aptitude install libicu48

On Windows, binaries are available here.

Creating times

julia> t = now()
Dec 3, 2012 12:58:52 PM EST

julia> t = ymd_hms(2013, 5, 2, 13, 45, 7)
May 2, 2013 1:45:07 PM EDT

julia> t = ymd_hms(2013, 5, 2, 13, 45, 7, "PST")
May 2, 2013 1:45:07 PM PDT

String formatting & parsing

julia> t = ymd_hms(2013, 3, 10, 1, 59, 59)
Mar 10, 2013 1:59:59 AM EST

julia> s = format("yyyy-MMMM-dd HH:mm:ss V", t)
"2013-March-10 01:59:59 EST"

julia> t2 = Calendar.parse("yyyy-MMMM-dd HH:mm:ss V", s)
Mar 10, 2013 1:59:59 AM EST

julia> t == t2
true

The format patterns are from Unicode Technical Standard #35. See here for details on ICU's implementation.

Extracting & setting fields

julia> t
May 2, 2013 1:45:07 PM PDT

julia> month(t)
5

julia> week(t)
18

Available fields:

year(d)
month(d) numbered 1-12
week(d) week of year
day(d) day of month
dayofyear(d)
dayofweek(d) Sunday = 1, ..., Saturday = 7
hour(d) 24hr clock
hour12(d) 12hr clock
minute(d)
second(d)

The two-argument form lets you set individual fields:

julia> t2 = now()
Dec 3, 2012 3:53:08 PM EST

julia> minute(t2, 7)
Dec 3, 2012 3:07:08 PM EST

julia> year(t2, 1984)
Dec 3, 1984 3:07:08 PM EST

Tests

julia> t
May 2, 2013 1:45:07 PM PDT

julia> isAM(t)
false
isAM(d) is time before noon?
isPM(d) is time after noon?
isleapyear(d) is leap year?

Durations

julia> t
May 2, 2013 1:45:07 PM PDT

julia> t + months(2)
Jul 2, 2013 1:45:07 PM PDT

julia> t + days(60)
Jul 1, 2013 1:45:07 PM PDT

julia> d = years(1) + minutes(44)
1 year + 44 minutes

julia> t + d
May 2, 2014 2:29:07 PM PDT

Available durations: years, months, weeks, days, hours, minutes, seconds

Timezones

julia> est = ymd_hms(2013, 3, 10, 1, 59, 59)
Mar 10, 2013 1:59:59 AM EST

julia> pst = timezone(est, "PST")  # change timezone
Mar 9, 2013 10:59:59 PM PST

julia> est + seconds(1)      # note daylight savings time transition
Mar 10, 2013 3:00:00 AM EDT

julia> pst + seconds(1)
Mar 9, 2013 11:00:00 PM PST

Ranges

Just as 1:2:10 represents the integers 1,3,5,7,9; <time1>:<duration>:<time2> represents the times <time1>, <time1>+<duration>, <time1>+2<duration>, ...

julia> t = now()
2012-12-04 10:24:19 PM EST

julia> t2 = t + minutes(4)
2012-12-04 10:28:19 PM EST

julia> r = t:minutes(1):t2
2012-12-04 10:24:19 PM EST:1 minute:2012-12-04 10:28:19 PM EST

julia> for x in r println(x) end
2012-12-04 10:24:19 PM EST
2012-12-04 10:25:19 PM EST
2012-12-04 10:26:19 PM EST
2012-12-04 10:27:19 PM EST
2012-12-04 10:28:19 PM EST

Localization (i18n)

Based on your system settings, dates will be displayed as:

China:

julia> Calendar.now()
2012-12-6 GMT-0500下午4时09分23秒

Germany:

julia> Calendar.now()
06.12.2012 16:08:36 GMT-05:00

France:

julia> Calendar.now()
6 déc. 2012 16:07:56 UTC-05:00

etc...