PikeHints/Calendar

Calendar

[ Start > PikeHints > Calendar ] [ Edit this Page | Show Page Versions | Show Raw Source ]

The Calendar module, part of the Pike core, is an extremely powerful tool for working with and manipulating time periods ranging from fractions of seconds up to Centuries and beyond. It's a sprawling set of classes and functions that often frustrates and confuses even long time Pike users. Hopefully some of the following tips can help ease the learning curve.

The hidden documentation

In addition to the module reference material that's shipped as part of the module code itself, there are a few documents tucked away in the Calendar.pmod directory within every Pike installation. There most important of these files is simply called "FAQ", and it contains a series of useful questions with (perhaps) surprisingly complete answers. Anyone interested in using the Calendar module should read this document before anything else.

Some examples

> Calendar.Time.TimeofDay tod = Calendar.now();
> tod->unix_time();
(2) Result: 1334089973
> tod->fraction_no();
(3) Result: 0.737028999

The documentation is a spread out I use:

- Many things of what you can do with Calendar is documented here: http://pike.ida.liu.se/generated/manual/modref/ex/predef_3A_3A/Calendar/Time/TimeofDay.html

- How you parse a date string: http://pike.ida.liu.se/generated/manual/modref/ex/predef_3A_3A/Calendar/YMD/Hour/parse.html

Favorite functions include (ways to get objects that represent particular periods of time):

Calendar.Week()->days();
Calendar.Week()->week_no();
Calendar.Week(2012,16)->days();              
Calendar.Day()->hours();
Calendar.Hour()->minutes();
Calendar.Hour()->seconds();

TimeRange consisting of some Day objects in the middle of may:

> Calendar.Day day_start = Calendar.Day(2012,5,12);
> day_start->distance(Calendar.Day(2012,5,22))->days();
(1) Result: ({ /* 10 elements */
               Day(Sat 12 May 2012),
               Day(Sun 13 May 2012),
               Day(Mon 14 May 2012),
               Day(Tue 15 May 2012),
               Day(Wed 16 May 2012),
               Day(Thu 17 May 2012),
               Day(Fri 18 May 2012),
               Day(Sat 19 May 2012),
               Day(Sun 20 May 2012),
               Day(Mon 21 May 2012)
           })> day_start->range(Calendar.Day(2012,5,22))->days();   
(4) Result: ({ /* 11 elements */
               Day(Sat 12 May 2012),
               Day(Sun 13 May 2012),
               Day(Mon 14 May 2012),
               Day(Tue 15 May 2012),
               Day(Wed 16 May 2012),
               Day(Thu 17 May 2012),
               Day(Fri 18 May 2012),
               Day(Sat 19 May 2012),
               Day(Sun 20 May 2012),
               Day(Mon 21 May 2012),
               Day(Tue 22 May 2012)
           })

And mixing Day and Second:

> Calendar.Second()->range(Calendar.Day(2012,5,22));        
(6) Result: Second(Tue 10 Apr 2012 23:17:27 CEST - Wed 23 May 2012 0:00 CEST)

How you then handle and test the timerange against others is documented here: http://pike.ida.liu.se/generated/manual/modref/ex/predef_3A_3A/Calendar/TimeRange.html

Other ways to create Hour, Minute, Second:

> Calendar.Hour(Calendar.Day(2012,05,22), 12, 1);  
(19) Result: Hour(Tue 22 May 2012 12:00 CEST)
> Calendar.Minute(Calendar.Day(2012,05,22), 12, 4);    
(20) Result: Minute(Tue 22 May 2012 12:04 CEST)
> Calendar.Second(Calendar.Day(2012,05,22), 12, 4, 12);
(21) Result: Second(Tue 22 May 2012 12:04:12 CEST)

Powered by PikeWiki2