20. Calendar

Module Calendar

Description

Time and day system

Q:  I need to parse some date in a non-strict format, like
   the one in the HTTP or mail protocol, or from a user web
   form.

A:  Calendar.dwim_day, or Calendar.dwim_time, should solve
   your problem.

     > Calendar.dwim_day("1/2/3");
     Result: Day(Thu 2 Jan 2003)
     > Calendar.dwim_day("1 aug 2001");
     Result: Day(Wed 1 Aug 2001)

     > Calendar.dwim_time("1 aug 2001 23:14 EDT");
     Result: Minute(Wed 1 Aug 2001 23:14 EDT)
     > Calendar.dwim_time("2001 2 3 23:14:23 UTC+9");
     Result: Second(Sat 3 Feb 2001 23:14:23 UTC+9)

   If it doesn't, and it should, report the problem to me
   and I'll see what I can do. Note that the timezones
   are rather unpredictable - if it doesn't get it, you
   will get the default (local) timezone.

-------------------------------------------------------------------------

Q:  The dwim_* functions are too slow.

A:  They are not written to be fast, but to do good guessing.

   If you know the format, you should use the Calendar.parse
   function:

     > Calendar.parse("%Y-%M-%D %h:%m","2040-11-08 2:46");
     Result: Minute(Thu 8 Nov 2040 2:46 CET)
     > Calendar.parse("%Y w%W %e %h:%m %p %z","1913 w4 monday 2:14 pm CET");
     Result: Minute(Mon 20 Jan 1913 14:14 CET)

   These are the format characters:
    %Y absolute year
    %y dwim year (70-99 is 1970-1999, 0-69 is 2000-2069)
    %M month (number, name or short name) (needs %y)
    %W week (needs %y)
    %D date (needs %y, %m)
    %d short date (20000304, 000304)
    %a day (needs %y)
    %e weekday (needs %y, %w)
    %h hour (needs %d, %D or %W)
    %m minute (needs %h)
    %s second (needs %m)
    %f fraction of a second (needs %s)
    %t short time (205314, 2053)
    %z zone
    %p "am" or "pm"
    %n empty string (to be put at the end of formats)

   and you can also use "%*[....]" to skip some characters,
   as in sscanf().

   If this is too slow, there is currently no solution in Pike
   to do this faster, except possibly sscanf and manual calculations/
   time object creation.

-------------------------------------------------------------------------

Q:  How do I get from unix time (time(2)) to a unit and back?

A:  Calendar.Unit("unix",time())
   unit->unix_time()

     > Calendar.Day("unix",987654321);
     Result: Day(Thu 19 Apr 2001)
     > Calendar.Second("unix",987654321);
     Result: Second(Thu 19 Apr 2001 6:25:21 CEST)

     > Calendar.Day()->unix_time();
     Result: 979081200

   Note that you will get the time for the start of the unit.
   Unix time is timezone independant.

   The day-of-time units (seconds, hours, etc) uses this
   as internal representation of time.

-------------------------------------------------------------------------

Q:  I'm a mad astronomer, how do I do the same conversions with
   julian day numbers?

A:  Julian day numbers are used as the internal representation
   for the day, and for most other bigger-than-time-of-day calculations.

     > Calendar.Day("julian",2454545);
     Result: Day(Wed 19 Mar 2008)
     > Calendar.Second("julian",2430122.0);
     Result: Second(Tue 6 May 1941 13:00:00 CET)

   Julian day numbers from day units and bigger are integers,
   representing the new julian number on that day. Julian day
   numbers from time of day units are represented in floats.

     > Calendar.Day()->julian_day();
     Result: 2451920
     > Calendar.Second()->julian_day();
     Result: 2451919.949595

   Watch out for the float precision, though. If you haven't
   compiled your Pike with --with-double-precision, this gives
   you awkwardly low precision - 6 hours.

-------------------------------------------------------------------------

Q:  How do I convert a "Second(Sat 3 Feb 2001 23:14:23 UTC+9)" object
   to my timezone?

A:  ->set_timezone(your timezone)

     > Calendar.dwim_time("2001 2 3 23:14:23 PST")
     	  ->set_timezone("Europe/Stockholm");
     Result: Second(Sun 4 Feb 2001 8:14:23 CET)

     > Calendar.dwim_time("2001 2 3 23:14:23 PST")
     	  ->set_timezone("locale");
     Result: Second(Sun 4 Feb 2001 8:14:23 CET)

-------------------------------------------------------------------------

Q:  How do I print my time object?

A:  ->format_xxx();

   You can either print it unit-sensitive,

     > Calendar.dwim_time("2001 2 3 23:14:23 PST")->format_nice();
     Result: "3 Feb 2001 23:14:23"
     > Calendar.Week()->format_nice();
     Result: "w2 2001"
     > Calendar.now()->format_nicez();
     Result: "10 Jan 10:51:15.489603 CET"

   or in a format not depending on the unit,

     > Calendar.Week()->format_ymd();
     Result: "2001-01-08"
     > Calendar.Day()->format_time();
     Result: "2001-01-10 00:00:00"

   This is all the formats:

   format_ext_time       "Wednesday, 10 January 2001 10:49:57"
   format_ext_time_short "Wed, 10 Jan 2001 10:49:57 CET"
   format_ext_ymd        "Wednesday, 10 January 2001"
   format_iso_time       "2001-01-10 (Jan) -W02-3 (Wed) 10:49:57 UTC+1"
   format_iso_ymd        "2001-01-10 (Jan) -W02-3 (Wed)"
   format_mod            "10:49"
   format_month          "2001-01"
   format_month_short    "200101"
   format_mtime          "2001-01-10 10:49"
   format_time           "2001-01-10 10:49:57"
   format_time_short     "20010110 10:49:57"
   format_time_xshort    "010110 10:49:57"
   format_tod            "10:49:57"
   format_tod_short      "104957"
   format_todz           "10:49:57 CET"
   format_todz_iso       "10:49:57 UTC+1"
   format_week           "2001-w2"
   format_week_short     "2001w2"
   format_iso_week       "2001-W02"
   format_iso_week_short "200102"
   format_xtime          "2001-01-10 10:49:57.539198"
   format_xtod           "10:49:57.539658"
   format_ymd            "2001-01-10"
   format_ymd_short      "20010110"
   format_ymd_xshort     "010110"

   format_ctime          "Wed Jan 10 10:49:57 2001\n"
   format_smtp           "Wed, 10 Jan 2001 10:49:57 +0100"
   format_http           "Wed, 10 Jan 2001 09:49:57 GMT"

-------------------------------------------------------------------------

Q:  How old am I?

A:  First, you need to create the time period representing your age.

     > object t=Calendar.dwim_time("1638 dec 23 7:02 pm")
     	  ->distance(Calendar.now());
     Result: Fraction(Thu 23 Dec 1638 19:02:00.000000 LMT -
     		       Wed 10 Jan 2001 10:53:33.032856 CET)

  Now, you can ask for instance how many years this is:

     > t->how_many(Calendar.Year);
     Result: 362

  Or how many 17 seconds it is:

     > t->how_many(Calendar.Second()*17);
     Result: 672068344

  A note here is to use ->distance, and not ->range, since that
  will include the destination unit too:

    > Calendar.dwim_day("00-01-02")->range(Calendar.Week(2000,2))
       ->how_many(Calendar.Day());
    Result: 15
    > Calendar.dwim_day("00-01-02")->distance(Calendar.Week(2000,2))
       ->how_many(Calendar.Day());
    Result: 8

-------------------------------------------------------------------------

Q:  In 983112378 days, what weekday will it be?

A:  (this weekday + 983112378) % 7   ;)

   or take this day, add the number, and ask the object:

     > (Calendar.Day()+983112378)->week_day_name();
     Result: "Saturday"

   "+int" will add this number of the unit to the unit;
   this means that Calendar.Year()+2 will move two years
   forward, but Calendar.now()+2 will not move at all
   - since now has zero size.

   To add a number of another time unit, simply do that:

     > Calendar.Day()+3*Calendar.Year();
     Result: Day(Sat 10 Jan 2004)
     > Calendar.Day()+3*Calendar.Minute()*134;
     Result: Minute(Wed 10 Jan 2001 6:42 CET - Thu 11 Jan 2001 6:42 CET)

   The last result here is because the resulting time still will
   be as long as the first.

-------------------------------------------------------------------------

Q:  Are there other calendars?

A:  Yes.

   Calendar.Day is really a shortcut to Calendar.ISO.Day.

   There is currently:

   Gregorian
	This is the base module for Julian style calendars;
	despite the name. Most calendars of today are in sync
	with the Gregorian calendar.
   ISO
	This inherits the Gregorian calendar to tweak it to
	conform to the ISO standards. Most affected are weeks,
	which starts on Monday in the ISO calendar.
	This is also the default calendar.
   Discordian
	The Discordian calendar as described in Principia Discordia
	is in sync with the Gregorian calendar (although some claim
	that it should be the Julian - I go with what I can read
	from my Principia Discordia). The module inherits and
	tweaks the Gregorian module.
   Coptic
	The Coptic calendar is by some sources ("St. Marks'
	Coptic Orthodox Church" web pages) is for now on in sync with
	the Gregorian Calendar, so this module too inherits
	and tweaks the Gregorian module. It needs to be
	adjusted for historical use.
   Julian
	This is the Julian calendar, with the small changes
	to the Gregorian calendar (leap years).
   Badi (Baha'i)
       The Badi calendar used by the Baha'i religion is based on the
       solar year. For the time being it is in sync with the Gregorian
       calendar.

   Islamic
	This is the Islamic calendar, using the 'Calendrical
	Calculations' rules for new moon. It is based
	directly on the YMD module.
   Stardate
	This is the (TNG) Stardate calendar, which consists
	of one time unit only, the Tick (1000 Tick is one earth year).
	It is based directly on TimeRanges.

-------------------------------------------------------------------------

Q:  How do I convert between the calendars?

A:  You give the unit to be converted to the constructor of
   the unit you want it to be.

   > Calendar.Coptic.Day(Calendar.dwim_day("14 feb 1983"));
   Result: Day(Mon 7 Ams 1699)
   > Calendar.Islamic.Minute(Calendar.dwim_day("14 feb 1983"));
   Result: Minute(aha 29 Rebîul-âchir 1403 AH 13:00 CET -
   		   ith 1 Djumâda'l-ûla 1403 AH 13:00 CET)
   > Calendar.Day(Calendar.Stardate.Tick(4711));
   Result: Day(Sat 17 Sep 2327 0:00 sharp)

-------------------------------------------------------------------------

Q:  Isn't there a <my country> calendar?

A:  <your country> uses the ISO calendar, with just different
   names for the months. Language is a parameter to the
   calendar units, as well as the timezone.

   You set the language by using ->set_language(yourlanguage).

     > t->set_language("pt")->format_ext_ymd();
     Result: "Quarta-feira, 10 Janeiro 2001"
     > t->set_language("roman")->format_ext_ymd();
     Result: "Mercurii dies, X Ianuarius MMDCCLIII ab urbe condita"

   Note that all languages aren't supported. If you miss your
   favourite language or I got it all wrong (or have some time over
   to help me out), look in the Language.pmod file and send me an
   update.

   Or send me a list of the weekdays and month names
   (please start with Monday and January).

   Currently, these languages are supported:

     name        code
     -------------------------------
     ISO                 (default, aka English)

     Afrikaans   af afr   (South Africa),
     Austrian    de_AT
     Basque      eu eus   (Spain)
     Catalan     ca cat   (Catalonia)
     Croatian    hr hrv
     Danish      da dan
     Dutch       nl nld
     English     en eng
     Estonian    et est
     Faroese     fo fao
     Finnish     fi fin
     French      fr fra
     Galician    gl glg   (Spain)
     German      de deu
     Greenlandic kl kal
     Hungarian   hu hun
     Icelandic   is isl
     Irish       ga gle   (Gaelic)
     Italian     it ita
     Latvian     lv lav
     Lithuanian  lt lit
     Norwegian   no nor
     Persian     fa fas   (Iran)
     Polish      pl pol
     Portugese   pt por
     Romanian    ro ron
     Serbian     sr srp   (Yugoslavia)
     Slovenian   sl slv
     Spanish     es spa
     Swedish     sv swe
     Turkish     tr
     Welsh       cy cym

     Latin       la lat
     Roman              (Roman Latin)

-------------------------------------------------------------------------

Q:  Isn't there a <whatever> calendar?

A:  Not if it isn't listed above. I'll appreciate any
   implementation help if you happen to have the time over
   to implement some calendar.

   I know I miss these:

     Chinese
     Jewish or Hebreic
     Maya

   Of these, the two first are based on astronomical events,
   which I haven't had the time to look into yet, but the
   last - Maya - is totally numeric.

-------------------------------------------------------------------------

Q:  I don't like that weeks starts on Mondays.
   Every school kids knows that weeks start on Sundays.

A:  According to the ISO 8601 standard, weeks start on mondays.

   If you don't like it, use Calendar.Gregorian.Day, etc.

-------------------------------------------------------------------------

Q:  How do I find out which days are red in a specific region?

A:  Events.<region>

   - contains the events for the region, as a SuperEvent.
   You can ask this object to filter out the holidays,

      Events.se->holidays();

   which will be a superevent containing only holidays.

   To use this information, you can for instance use ->scan,
   here in an example to see what red days there are in Sweden
   the current month:

     > Calendar.Events.se->filter_flag("h")->scan(Calendar.Month());
     Result: ({ /* 6 elements */
    		   Day(Sun 7 Jan 2001),
    		   Day(Sun 14 Jan 2001),
    		   Day(Sun 21 Jan 2001),
    		   Day(Sun 28 Jan 2001),
    		   Day(Sat 6 Jan 2001),
    		   Day(Mon 1 Jan 2001)
    	       })

-------------------------------------------------------------------------

Q:  How accurate are the events information?

A:  For some regions, very. For most regions, not very.

   The first reason is lack of information of this kind on
   the web, especially sorted into useful rules (like "the
   third monday after 23 dec", not "8 jan").

   The second reason is lack of time and interest to do
   research, which is a rather tedious job.

   If you want to help, the check your region in the
   events/regions file and send us <pike@roxen.com> a patch.

   Don't send me "the x region is all wrong!" mails without
   telling me what it should look like.

-------------------------------------------------------------------------

Q:  My timezone says it's DST. It's wrong.

A:  No it isn't.  But:

   o The local timezone detector failed to find your timezone by
     itself, or found the wrong timezone.

   o or you use the wrong timezone.

   To make sure the right timezone is used, use the standard
   timezone names. Those aren't "CET" or "PST", but
   "Europe/Amsterdam" or "America/Dawson".

   OR this may be in the future and you have a changed DST
   rule and uses an old Pike. Then you can either download
   a new version or download new timezone data files from
   the ftp address below (if the internet still is there).
FIXME

This needs to be reformatted as documentation.


InheritISO_UTC

inherit ISO_UTC : ISO_UTC

Description

Symbol lookups directly in Calendar default to looking up the same symbol in Calendar.ISO_UTC.


ConstantII

constantint Calendar.II

Description

Recongnition constant for Calendar module API 2.


Constantnulltimerange

constant Calendar.nulltimerange = TimeRange

Description

This represents the null time range, which, to differ from the zero time range (the zero-length time range), isn't placed in time. This is the result of for instance `& between two strict non-overlapping timeranges - no time at all.

It has a constant, is_nulltimerange, which is non-zero. `! on this timerange is true.

Class Calendar.Calendar

Description

This is the base class of the calendars.


Methodnow

Calendar.TimeRanges.TimeRangenow()

Description

Give the zero-length time period of the current time.

Class Calendar.Ruleset

Description

This is the container class for rules.


Method`==

bool res = Calendar.Ruleset() == other


Methodclone

this_programclone()


Methodset_abbr2zone

this_programset_abbr2zone(mapping(string:string) abbr2zone)

Description

Sets the guess-mapping for timezones. Default is the mapping:

AbbreviationInterpretationUTC
AMTAmerica/ManausUTC-4
ASTAmerica/CuracaoUTC-4
CDTAmerica/Costa_RicaUTC-5
CSTAmerica/El SalvadorUTC-6
ESTAmerica/PanamaUTC-5
GSTAsia/DubaiUTC+4
ISTAsia/JerusalemUTC+2
WSTAustralia/PerthUTC+8
See also

YMD.parse


Methodset_language

this_programset_language(string|Calendar.Rule.Languagelang)


Methodset_rule

this_programset_rule(Calendar.Rule.Language|Calendar.Rule.Timezonerule)


Methodset_timezone

this_programset_timezone(string|Calendar.Rule.Timezonet)

Class Calendar.SuperTimeRange

Description

This class handles the cases where you have a time period with holes. These can be created by the ^ or | operators on time ranges.


InheritTimeRange

inherit TimeRange : TimeRange


Methodcreate

Calendar.SuperTimeRangeCalendar.SuperTimeRange(array(TimeRange) parts)

Description

A SuperTimeRange must have at least two parts, two time ranges. Otherwise, it's either not a time period at all or a normal time period.

Module Calendar.Austrian

Description

Same as the ISO calendar, but with austrian as the default language.

This calendar exist only for backwards compatible purposes.


InheritISO

inherit Calendar.ISO : ISO

Module Calendar.Badi

Description

This is the Badi calendar, used in the Baha'i religion.


InheritYMD

inherit Calendar.YMD : YMD


Methoddaystart_offset

intdaystart_offset()

Description

Returns the offset to the start of the time range object

Class Calendar.Badi.Vahid


InheritYMD

inherit YMD : YMD


Methodyear

Yearyear()
Yearyear(intn)
Yearyear(stringname)

Description

Return a year in the vahid by number or name:

vahid->year("Alif")

Module Calendar.Bahai

Description

This is an alias for Calendar.Badi.


InheritBadi

inherit Badi : Badi

Module Calendar.Coptic

Description

This is the Coptic Orthodox Church calendar, that starts the 11th or 12th September and has 13 months.

Note

The (default) names of the months are different then other the emacs calendar; I do not know which ones are used - the difference seem to be only the transcription of the phonetic sounds (B <-> P, etc).

I do not know for how long back the calendar is valid, either. My sources claim that the calendar is synchronized with the Gregorian calendar, which is odd.


InheritGregorian

inherit Calendar.Gregorian : Gregorian

Module Calendar.Discordian

Description

The Discordian calendar, as described on page 34 in the fourth edition of Principia Discordia.

Chaotic enough, it's quite simpler then the Gregorian calendar; weeks are 5 days, and evens up on a year. Months are 73 days.

The leap day is inserted at the 60th day of the first month (Chaos), giving the first month 74 days. The description of the calendar is a "perpetual date converter from the gregorian to the POEE calendar", so the leap years are the same as the gregorians.

The Principia calls months "seasons", but for simplicity I call them months in this calendar.

If anyone know more about how to treat the leap day - now it is inserted in the month and week where it lands, rather then being separated from month and weeks, I'm interested to know.

- Mirar, Pope of POEE.


InheritGregorian

inherit Calendar.Gregorian : Gregorian

Module Calendar.Event

Class Calendar.Event.Date

Description

This class represents the event of a given gregorian date. For instance, Event.Date(12,10)->next(Day()) finds the next 12 of October.


InheritDay_Event

inherit Day_Event : Day_Event


Methodcreate

Calendar.Event.DateCalendar.Event.Date(int(1..31)month_day, int(1..12)month)

Description

The event is created by a given month day and a month number (1=January, 12=December).

Class Calendar.Event.Date_Weekday

Description

This class represents the event that a given gregorian date appears a given weekday. For instance, Event.Date_Weekday(12,10,5)->next(Day()) finds the next 12 of October that is a friday.


InheritDay_Event

inherit Day_Event : Day_Event


Methodcreate

Calendar.Event.Date_WeekdayCalendar.Event.Date_Weekday(intmonth_day, intmonth, intweekday)

Description

The event is created by a given month day, a month number (1=January, 12=December), and a weekday number (1=Monday, 7=Sunday).

Note

The week day numbers used are the same as the day of week in the ISO calendar - the Gregorian calendar has 1=Sunday, 7=Saturday.

Class Calendar.Event.Day_Event

Description

Day_Event is an abstract class, extending Event for events that are single days, using julian day numbers for the calculations.


InheritEvent

inherit Event : Event


ConstantNODAY

constantint Calendar.Event.Day_Event.NODAY

Description

Returned from scan_jd if the even searched for did not exist.


Constantis_day_event

constantint Calendar.Event.Day_Event.is_day_event

Description

This constant may be used to identify Day_Event objects.


Methodnext

Calendar.TimeRanges.TimeRangenext(Calendar.TimeRanges.TimeRange|voidfrom, void|boolincluding)

Description

Uses the virtual method scan_jd.

See also

Event.next


Methodprevious

Calendar.TimeRanges.TimeRange|zeroprevious(Calendar.TimeRanges.TimeRange|voidfrom, void|boolincluding)

Description

Uses the virtual method scan_jd.

See also

Event.previous


Methodscan_jd

intscan_jd(Calendar.Calendarrealm, intjd, int(-1)|int(1)direction)

Description

This method has to be defined, and is what really does some work.

Parameter direction
1

Forward (next),

-1

Backward (previous).

Returns

It should return the next or previous julian day (>jd) when the event occurs, or the constant NODAY if it doesn't.

Class Calendar.Event.Easter

Description

This class represents an easter.


InheritDay_Event

inherit Day_Event : Day_Event


Methodcreate

Calendar.Event.EasterCalendar.Event.Easter(void|intshift)

Description

shift is the year to shift from old to new style easter calculation. Default is 1582.


Methodeaster_yd

inteaster_yd(inty, intyjd, intleap)

Description

Calculates the year day for the easter.

Class Calendar.Event.Easter_Relative

Description

This class represents an easter relative event.


InheritEaster

inherit Easter : Easter


Methodcreate

Calendar.Event.Easter_RelativeCalendar.Event.Easter_Relative(stringid, stringname, intoffset)

Class Calendar.Event.Event

Description

Event is an abstract class, defining what methods an Event need to have.


Constantis_event

constantint Calendar.Event.Event.is_event

Description

This constant may be used to identify an event object.


Method`|
Method``|

SuperEvent res = Calendar.Event.Event() | with
SuperEvent res = with | Calendar.Event.Event()

Description

Joins several events into one SuperEvent.


Methoddescribe

stringdescribe()

Description

Returns a description of the event.


Methodnext
Methodprevious

Calendar.TimeRanges.TimeRangenext(void|Calendar.TimeRanges.TimeRangefrom, void|boolincluding)
Calendar.TimeRanges.TimeRangeprevious(void|Calendar.TimeRanges.TimeRangefrom, void|boolincluding)

Description

This calculates the next or previous occurance of the event, from the given timerange's start, including any event occuring at the start if that flag is set.

It returns zero if there is no next event.

These methods are virtual in the base class.


Methodscan

array(Calendar.TimeRanges.TimeRange) scan(Calendar.TimeRanges.TimeRangein)

Description

This calculates the eventual events that is contained or overlapped by the given timerange. scan uses next, if not overloaded.

Example

Calendar.Event.Easter()->scan(Calendar.Year(2000)) => ({ Day(Sun 23 Apr 2000) })

Note

scan can return an array of overlapping timeranges.

This method must use in->calendar_object->type to create the returned timeranges, and must keep the ruleset.


Methodscan_events

mapping(Calendar.TimeRanges.TimeRange:Event) scan_events(Calendar.TimeRanges.TimeRangein)

Description

Returns a mapping with time ranges mapped to events.

Class Calendar.Event.Gregorian_Fixed

Description

A set date of year, counting leap day in February, used for the Gregorian fixed events in the events list.

See also

Julian_Fixed


InheritDay_Event

inherit Day_Event : Day_Event


Constantis_fixed

constantint Calendar.Event.Gregorian_Fixed.is_fixed

Description

This constant may be used to identify Gregorian_Fixed objects.


Methodcreate

Calendar.Event.Gregorian_FixedCalendar.Event.Gregorian_Fixed(stringid, stringname, int(1..31)month_day, int(1..12)month, intextra)

Class Calendar.Event.Julian_Fixed

Description

A set date of year, counting leap day in February, used for the Gregorian fixed events in the events list.

See also

Gregorian_Fixed


InheritGregorian_Fixed

inherit Gregorian_Fixed : Gregorian_Fixed


Constantis_julian_fixed

constantint Calendar.Event.Julian_Fixed.is_julian_fixed

Description

This constant may be used to identify Julian_Fixed objects.

Class Calendar.Event.Monthday_Weekday

Description

This class represents the event that a given gregorian day of month appears a given weekday. For instance, Event.Monthday_Weekday(13,5)->next(Day()) finds the next friday the 13th.


InheritDay_Event

inherit Day_Event : Day_Event


Methodcreate

Calendar.Event.Monthday_WeekdayCalendar.Event.Monthday_Weekday(intmonth_day, intweekday)

Description

The event is created by a given month day, and a weekday number (1=Monday, 7=Sunday).

Note

The week day numbers used are the same as the day of week in the ISO calendar - the Gregorian calendar has 1=Sunday, 7=Saturday.

Class Calendar.Event.Monthday_Weekday_Relative

Description

This class represents a monthday weekday relative event or n:th special weekday event, e.g. "fourth sunday before 24 dec" => md=24,mn=12,wd=7,n=-4


InheritGregorian_Fixed

inherit Gregorian_Fixed : Gregorian_Fixed


Methodcreate

Calendar.Event.Monthday_Weekday_RelativeCalendar.Event.Monthday_Weekday_Relative(stringid, stringname, int(1..31)md, int(1..12)mn, int(1..7)_wd, int_n, void|bool_inclusive)

Class Calendar.Event.Nameday

Description

This is created by the Namedays classes to represent an event for a name.


InheritDay_Event

inherit Day_Event : Day_Event


Constantis_nameday

constantint Calendar.Event.Nameday.is_nameday

Description

This constant may be used to identify Nameday objects.

Class Calendar.Event.Namedays

Description

This contains a ruleset about namedays.


InheritEvent

inherit Event : Event


Constantis_namedays

constantint Calendar.Event.Namedays.is_namedays

Description

This constant may be used to identify Namedays.


Methodnamedays

mapping(Calendar.TimeRanges.TimeRange:array(string)) namedays(Calendar.TimeRanges.TimeRanget)

Description

Gives back an table of days with names that occur during the time period. Note that days without names will not appear in the returned mapping.


Methodnames

array(string) names(Calendar.TimeRanges.TimeRanget)

Description

Gives back an array of names that occur during the time period, in no particular order.

Class Calendar.Event.NullEvent

Description

A non-event.


InheritEvent

inherit Event : Event


Constantis_nullevent

constantint Calendar.Event.NullEvent.is_nullevent

Description

This constant may be used to identify a NullEvent.

Class Calendar.Event.Orthodox_Easter_Relative

Description

This class represents an orthodox easter relative event.


InheritEaster_Relative

inherit Easter_Relative : Easter_Relative


Methodcreate

Calendar.Event.Orthodox_Easter_RelativeCalendar.Event.Orthodox_Easter_Relative(stringid, stringname, intoffset)

Class Calendar.Event.Solar

Description

This class represents a solar event as observed from Earth.

The event_type is one of

0

Northern hemisphere spring equinox.

1

Northern hemisphere summer solstice.

2

Northern hemisphere autumn equinox.

3

Northern hemisphere winter solstice.


InheritDay_Event

inherit Day_Event : Day_Event


Constantperiodic_table

protected constant Calendar.Event.Solar.periodic_table

Description
Array
array(float) 0..
Array
float0

Amplitude in days.

float1

Cosine phase in radians in year 2000.

float2

Period in radians/year.


Variableevent_type

int|void Calendar.Event.Solar.event_type


Method__create__

protectedlocalvoid__create__(int|voidevent_type)


Methodcreate

Calendar.Event.SolarCalendar.Event.Solar(int|voidevent_type)


Methodprevious

Calendar.TimeRanges.TimeRangeprevious(Calendar.TimeRanges.TimeRange|voidfrom, void|boolincluding)

Description

Uses the virtual method scan_jd.

See also

Event.previous


Methodscan_jd

intscan_jd(Calendar.Calendarrealm, intjd, int(1)|int(-1)direction)

Note

Returns unixtime in UTC to avoid losing the decimals!


Methodsolar_event

array(int|float) solar_event(inty)

Description

Calculate the next event.

Based on Meeus Astronomical Algorithms Chapter 27.

Class Calendar.Event.SuperEvent

Description

This class holds any number of events, and adds the functionality of event flags.

Note

Scanning (scan_events,next,etc) will drop flag information. Dig out what you need with holidays et al first.


InheritEvent

inherit Event : Event


Methodfilter_flag
Methodholidays
Methodflagdays

SuperEventfilter_flag(stringflag)
SuperEventholidays()
SuperEventflagdays()

Description

Filter out the events that has a certain flag set. Holidays (flag "h") are the days that are marked red in the calendar (non-working days), Flagdays (flag "f") are the days that the flag should be visible in (only some countries).

Class Calendar.Event.SuperNamedays

Description

Container for merged Namedays objects. Presumes non-overlapping namedays


InheritEvent

inherit Event : Event


Variablenamedayss
Variableid

array(Nameday) Calendar.Event.SuperNamedays.namedayss
string Calendar.Event.SuperNamedays.id


Method__create__

protectedlocalvoid__create__(array(Nameday) namedayss, stringid)


Methodcreate

Calendar.Event.SuperNamedaysCalendar.Event.SuperNamedays(array(Nameday) namedayss, stringid)

Class Calendar.Event.TZShift_Event

Description

Event containing information about when a timezone is changed.


InheritEvent

inherit Event : Event


Methodscan_history

protectedCalendar.TimeRanges.TimeRangescan_history(Calendar.Rule.Timezonetz, Calendar.TimeRanges.TimeRangefrom, intdirection, boolincluding)


Methodscan_rule

protectedCalendar.TimeRanges.TimeRange|zeroscan_rule(Calendar.Rule.Timezonetz, Calendar.TimeRanges.TimeRangefrom, intdirection, intincluding)


Methodscan_shift

protectedCalendar.TimeRanges.TimeRangescan_shift(Calendar.Rule.Timezonetz, Calendar.TimeRanges.TimeRangefrom, intdirection, intincluding)

Class Calendar.Event.Weekday

Description

This class represents any given weekday. For instance, Event.Weekday(5)->next(Day()) finds the next friday.

These are also available as the pre-defined events Events.monday, Events.tuesday, Events.wednesday, Events.thursday, Events.friday, Events.saturday and Events.sunday.


InheritDay_Event

inherit Day_Event : Day_Event


Methodcreate

Calendar.Event.WeekdayCalendar.Event.Weekday(intweekday, void|stringid)

Description

The event is created by a given weekday number (1=Monday, 7=Sunday).

Note

The week day numbers used are the same as the day of week in the ISO calendar - the Gregorian calendar has 1=Sunday, 7=Saturday.

Module Calendar.Events

Description

The Event system

Q: How do I find out which days are red in a specific region?

A: Events.<region>

- contains the events for the region, as a SuperEvent. You can ask this object to filter out the holidays,

Events.se.holidays();

Which will be a superevent containing only holidays.

To use this information, you can for instance use ->scan, here in an example to see what red days there were in Sweden in 2001

>Calendar.Events.se->filter_flag("h")->scan(Calendar.Month());
      Result:({/* 6 elements */
     		   Day(Sun 7 Jan 2001),
     		   Day(Sun 14 Jan 2001),
     		   Day(Sun 21 Jan 2001),
     		   Day(Sun 28 Jan 2001),
     		   Day(Sat 6 Jan 2001),
     		   Day(Mon 1 Jan 2001)

Method`[]
Method`->

Event.Event`[](stringregion)
Event.Event`->(stringregion)

Description

return the Event object for the specified region or the specified named event.

Module Calendar.Gregorian

Description

This is the standard conservative christian calendar, used regularly in some countries - USA, for instance - and which derivate - the ISO calendar - is used in most of Europe.


InheritYMD

inherit Calendar.YMD : YMD

Module Calendar.ISO

Description

This is the standard western calendar, which is a derivate of the Gregorian calendar, but with weeks that starts on Monday instead of Sunday.


InheritGregorian

inherit Calendar.Gregorian : Gregorian

Module Calendar.ISO_UTC

Description

Calendar.ISO with the timezone set to "UTC".


InheritISO

inherit ISO : ISO

Module Calendar.Islamic

Description

This is the islamic calendar. Due to some sources, they decide the first day of the new months on a month-to-month basis (sightings of the new moon), so it's probably not that accurate. If someone can confirm (or deny) accuracy better than that, please contact me so I can change this statement.

It's vaugely based on rules presented in algorithms by Dershowitz, Reingold and Clamen, 'Calendrical Calculations'. It is the same that's used in Emacs calendar mode.

Bugs

I have currently no idea how the arabic countries count the week. Follow the same rules as ISO for now... The time is also suspicious; the day really starts at sunset and not midnight, the hours of the day is not correct. Also don't know what to call years before 1 - go for "BH"; positive years are "AH", anno Hegirac.


InheritYMD

inherit Calendar.YMD : YMD

Module Calendar.Julian

Description

This is the Julian calendar, conjured up by the old Romans when their calendar were just too weird. It was used by the christians as so far as the 18th century in some parts of the world. (Especially the protestantic and orthodox parts.)

Note

Don't confuse the julian day with the Julian calendar. The former is just a linear numbering of days, used in the Calendar module as a common unit for absolute time.


InheritGregorian

inherit Calendar.Gregorian : Gregorian

Module Calendar.Rule

Class Calendar.Rule.Timezone

Description

Contains a time zone.


Methodcreate

Calendar.Rule.TimezoneCalendar.Rule.Timezone(intoffset, stringname)

Parameter offset

Offset to UTC, not counting DST.

Parameter name

The name of the time zone.


Methodraw_utc_offset

intraw_utc_offset()

Description

Returns the offset to UTC, not counting DST.


Methodtz_jd

array(int) tz_jd(intjulian_day)

FIXME

This method takes one integer argument, ignores it and returns an array with the UTC offset and the timezone name.


Methodtz_ux

array(int) tz_ux(intunixtime)

FIXME

This method takes one integer argument, ignores it and returns an array with the UTC offset and the timezone name.

Module Calendar.Stardate

Description

This implements TNG stardates.


Methodnow

cTicknow()

Description

Give the zero-length time period of the current time.

Class Calendar.Stardate.cTick


InheritTimeRange

inherit Calendar.TimeRange : TimeRange


Methodcreate

Calendar.Stardate.cTickCalendar.Stardate.cTick(mixed ... args)
Calendar.Stardate.cTickCalendar.Stardate.cTick(int|floatdate)
Calendar.Stardate.cTickCalendar.Stardate.cTick()

Description

Apart from the standard creation methods (julian day, etc), you can create a stardate from the stardate number. The length of the period will then be zero.

You can also omit any arguments to create now.

Bugs

Since the precision is limited to the float type of Pike you can get non-precise results:

> Calendar.Second(Calendar.Stardate.Day(Calendar.Year()));
Result: Second(Fri 31 Dec 1999 23:59:18 CET - Sun 31 Dec 2000 23:59:18 CET)

Methodformat_long
Methodformat_short
Methodformat_vshort

stringformat_long(void|intprecision)
stringformat_short(void|intprecision)
stringformat_vshort(void|intprecision)

Description

Format the stardate tick nicely. Precision is the number of decimals. Defaults to 3.

long"-322537.312"
short"77463.312"(w/o >100000-component)
vshort"7463.312"(w/o >10000-component)

Methodnumber_of_days

intnumber_of_days()

Description

This gives back the Gregorian/Earth/ISO number of days, for convinience and conversion to other calendars.


Methodnumber_of_seconds

intnumber_of_seconds()

Description

This gives back the Gregorian/Earth/ISO number of seconds, for convinience and conversion to other calendars.


Methodtic

floattic()

Description

This gives back the start of the stardate period, as a float.


Methodtics

floattics()

Description

This gives back the number of stardate tics in the period.

Module Calendar.Swedish

Description

Same as the ISO calendar, but with Swedish as the default language.

This calendar exist only for backwards compatible purposes.


InheritISO

inherit Calendar.ISO : ISO

Module Calendar.TZnames

Description

This module contains listnings of available timezones, in some different ways


Constantabbr2zones

constant Calendar.TZnames.abbr2zones = mapping(string:array(string))

Description

This mapping is used to look up abbreviation to the possible regional zones.

It looks like this:

([ "CET": ({ "Europe/Stockholm", <i>[...]</i> }),
   "CST": ({ "America/Chicago", "Australia/Adelaide", <i>[...]</i> }),
   <i>[...]</i> }),

Note this: Just because it's noted "CST" doesn't mean it's a unique timezone. There is about 7 *different* timezones that uses "CST" as abbreviation; not at the same time, though, so the DWIM routines checks this before it's satisfied. Same with some other timezones.

For most timezones, there is a number of region timezones that for the given time are equal. This is because region timezones include rules about local summer time shifts and possible historic shifts.

The YMD.parse functions can handle timezone abbreviations by guessing.


Constantzones

constant Calendar.TZnames.zones = mapping(string:array(string))

Description

This constant is a mapping that can be used to loop over to get all the region-based timezones.

It looks like this:

([ "America": ({ "Los_Angeles", "Chicago", <i>[...]</i> }),
   "Europe":  ({ "Stockholm", <i>[...]</i> }),
   <i>[...]</i> }),

Please note that loading all the timezones can take some time, since they are generated and compiled on the fly.


Method_zone_tab
Methodzone_tab

string_zone_tab()
array(array) zone_tab()

Description

This returns the raw respectively parsed zone tab file from the timezone data files.

The parsed format is an array of zone tab line arrays,

({ string country_code,
   string position,
   string zone_name,
   string comment })

To convert the position to a Geography.Position, simply feed it to the constructor.


Methodzonenames

array(string) zonenames()

Description

This reads the zone.tab file and returns name of all standard timezones, like "Europe/Belgrade".

Module Calendar.Time

Description

Base for time of day in calendars, ie calendars with hours, minutes, seconds

This module can't be used by itself, but is inherited by other modules (ISO by YMD, for instance).


InheritTimeRanges

inherit TimeRanges : TimeRanges

Class Calendar.Time.Fraction

Description

A Fraction is a part of a second, and/or a time period with higher resolution then a second.

It contains everything that is possible to do with a Second, and also some methods of grabbing the time period with higher resolution.

Note

Internally, the fraction time period is measured in nanoseconds. A shorter or more precise time period then in nanoseconds is not possible within the current Fraction class.


InheritSecond

inherit Second : Second


Methodcreate

Calendar.Time.FractionCalendar.Time.Fraction()
Calendar.Time.FractionCalendar.Time.Fraction("unix", int|floatunixtime)
Calendar.Time.FractionCalendar.Time.Fraction("unix", int|floatunixtime, int|floatlen)
Calendar.Time.FractionCalendar.Time.Fraction(inty, intm, intd, inth, intm, ints, intns)

Description

It is possible to create a Fraction in three ways, either "now" with no arguments or from a unix time (as from time(2)), or the convenience way from ymd-hms integers.

If created from unix time, both the start of the period and the size of the period can be given in floats, both representing seconds. Note that the default float precision in pike is rather low (same as 'float' in C, the 32 bit floating point precision, normally about 7 digits), so beware that the resolution might bite you. (Internally in a Fraction, the representation is an integer.)

If created without explicit length, the fraction will always be of zero length.


Methodnow

TimeofDay now()

Description

Give the zero-length time period of the current time.


Methodset_ruleset
Methodruleset

Calendar set_ruleset(Rulesetr)
Ruleset ruleset()

Description

Set or read the ruleset for the calendar. set_ruleset returns a new calendar object, but with the new ruleset.


Methodset_timezone
Methodtimezone

Calendar set_timezone(Timezonetz)
Calendar set_timezone(string|Timezonetz)
TimeZone timezone()

Description

Set or get the current timezone (including dst) rule. set_timezone returns a new calendar object, as the called calendar but with another set of rules.

Example:

> Calendar.now();
Result: Fraction(Fri 2 Jun 2000 18:03:22.010300 CET)
> Calendar.set_timezone(Calendar.Timezone.UTC)->now();
Result: Fraction(Fri 2 Jun 2000 16:03:02.323912 UTC)

Class Calendar.Time.Hour


InheritTimeofDay

inherit TimeofDay : TimeofDay

Class Calendar.Time.Minute


InheritTimeofDay

inherit TimeofDay : TimeofDay

Class Calendar.Time.Second


InheritTimeofDay

inherit TimeofDay : TimeofDay

Class Calendar.Time.SuperTimeRange


InheritSuperTimeRange

inherit TimeRanges.SuperTimeRange : SuperTimeRange


Methodsecond
Methodseconds
Methodnumber_of_seconds
Methodminute
Methodminutes
Methodnumber_of_minutes
Methodhour
Methodhours
Methodnumber_of_hours

Second second()
Second second(intn)
array(Second) seconds()
array(Second) seconds(intfirst, intlast)
intnumber_of_seconds()
Minute minute()
Minute minute(intn)
array(Minute) minutes()
array(Minute) minutes(intfirst, intlast)
intnumber_of_minutes()
Hour hour()
Hour hour(intn)
array(Hour) hours()
array(Hour) hours(intfirst, intlast)
intnumber_of_hours()

Description

Similar to TimeofDay, the Time::SuperTimeRange has a number of methods for digging out time parts of the range. Since a SuperTimeRange is a bit more complex - the major reason for its existance it that it contains holes, this calculation is a bit more advanced too.

If a range contains the seconds, say, 1..2 and 4..5, the third second (number 2, since we start from 0) in the range would be number 4, like this:

no   means this second
0    1
1    2
2    4      <- second three is missing,
3    5         as we don't have it in the example range

number_of_seconds() will in this example therefore also report 4, not 5, even if the time from start of the range to the end of the range is 5 seconds.

Class Calendar.Time.TimeofDay

Description

Virtual class used by e.g. Hour.


InheritTimeRange

inherit TimeRange : TimeRange


Methodcall_out

voidcall_out(function(:void) fun, mixed...args)

Description

Creates a call_out to this point in time.


Methodcreate

Calendar.Time.TimeofDayCalendar.Time.TimeofDay()
Calendar.Time.TimeofDayCalendar.Time.TimeofDay(intunixtime)

Description

In addition to the wide range of construction arguments for a normal TimeRange (see TimeRange.create), a time of day can also be constructed with unixtime as single argument consisting of the unix time - as returned from time(2) - of the time unit start.

It can also be constructed without argument, which then means "now", as in "this minute".


Methoddatetime

mappingdatetime()

Description

This gives back a mapping with the relevant time information (representing the start of the period);

 ([ "year":     int        // year number (2000 AD=2000, 1 BC==0)
    "month":    int(1..)   // month of year
    "day":      int(1..)   // day of month
    "yearday":  int(1..)   // day of year
    "week":     int(1..)   // week of year
    "week_day": int(1..)   // day of week (depending on calendar)
 
    "hour":     int(0..)   // hour of day, including dst
    "minute":   int(0..59) // minute of hour
    "second":   int(0..59) // second of minute
    "fraction": float      // fraction of second
    "timezone": int        // offset to utc, including dst
 
    "unix":     int        // unix time
    "julian":   float      // julian day
 ]);

Methodformat_iso_ymd
Methodformat_ymd
Methodformat_ymd_short
Methodformat_ymd_xshort
Methodformat_iso_week
Methodformat_iso_week_short
Methodformat_week
Methodformat_week_short
Methodformat_month
Methodformat_month_short
Methodformat_iso_time
Methodformat_time
Methodformat_time_short
Methodformat_iso_short
Methodformat_time_xshort
Methodformat_mtime
Methodformat_xtime
Methodformat_tod
Methodformat_xtod
Methodformat_mod
Methodformat_nice
Methodformat_nicez

stringformat_iso_ymd()
stringformat_ymd()
stringformat_ymd_short()
stringformat_ymd_xshort()
stringformat_iso_week()
stringformat_iso_week_short()
stringformat_week()
stringformat_week_short()
stringformat_month()
stringformat_month_short()
stringformat_iso_time()
stringformat_time()
stringformat_time_short()
stringformat_iso_short()
stringformat_time_xshort()
stringformat_mtime()
stringformat_xtime()
stringformat_tod()
stringformat_xtod()
stringformat_mod()
stringformat_nice()
stringformat_nicez()

Description

Format the object into nice strings;

iso_ymd        "2000-06-02 (Jun) -W22-5 (Fri)" [2]
ext_ymd        "Friday, 2 June 2000" [2]
ymd            "2000-06-02"
ymd_short      "20000602"
ymd_xshort     "000602" [1]
iso_week       "2000-W22"
iso_week_short "2000W22"
week           "2000-w22" [2]
week_short     "2000w22" [2]
month          "2000-06"
month_short    "200006" [1]
iso_time       "2000-06-02 (Jun) -W22-5 (Fri) 20:53:14 UTC+1" [2]
ext_time       "Friday, 2 June 2000, 20:53:14" [2]
ctime          "Fri Jun  4 20:53:14 2000\n" [2] [3]
http           "Fri, 02 Jun 2000 19:53:14 GMT" [4]
time           "2000-06-02 20:53:14"
time_short     "20000602 20:53:14"
time_xshort    "000602 20:53:14"
iso_short      "20000602T20:53:14"
mtime          "2000-06-02 20:53"
xtime          "2000-06-02 20:53:14.000000"
todz           "20:53:14 CET"
todz_iso       "20:53:14 UTC+1"
tod            "20:53:14"
tod_short      "205314"
xtod           "20:53:14.000000"
mod            "20:53"
nice           "2 Jun 20:53", "2 Jun 2000 20:53:14" [2][5]
nicez          "2 Jun 20:53 CET" [2][5]
smtp           "Fri, 2 Jun 2000 20:53:14 +0100" [6]
commonlog      "02/Jun/2000:20:53:14 +0100" [2]
[1] note conflict (think 1 February 2003)
[2] language dependent
[3] as from the libc function ctime()
[4] as specified by the HTTP standard; this is always in GMT, ie, UTC. The timezone calculations needed will be executed implicitly. It is not language dependent.
[5] adaptive to type and with special cases for yesterday, tomorrow and other years
[6] as seen in Date: headers in mails

Methodhour_no
Methodminute_no
Methodsecond_no
Methodfraction_no

inthour_no()
intminute_no()
intsecond_no()
floatfraction_no()

Description

This gives back the number of the time unit, on this day. Fraction is a float number, 0<=fraction<1.


Methodhour
Methodhours
Methodnumber_of_hours

Hour hour()
Hour hour(intn)
array(Hour) hours()
array(Hour) hours(intfirst, intlast)
intnumber_of_hours()

Description

hour() gives back the timerange representing the first or nth Hour of the called object. Note that hours normally starts to count at zero, so ->hour(2) gives the third hour within the range.

An Hour is in the Calendar perspective as any other time range not only 60 minutes, but also one of the (normally) 24 hours of the day, precisely.

hours() give back an array of all the hours containing the time periods called. With arguments, it will give back a range of those hours, in the same enumeration as the n to hour().

number_of_hours() simple counts the number of hours containing the called time period.

Note: The called object doesn't have to *fill* all the hours it will send back, it's enough if it exist in those hours:

    > object h=Calendar.Time.Hour();
    Result: Hour(265567)
    > h->hours();
    Result: ({ /* 1 element */
                Hour(265567)
            })
    > h+=Calendar.Time.Minute();
    Result: Minute(265567:01+60m)
    > h->hours();
    Result: ({ /* 2 elements */
                Hour(265567),
                Hour(265568)
            })
    

Methodjulian_day

floatjulian_day()

Description

This calculates the corresponding julian day, from the time range. Note that the calculated day is the beginning of the period, and is a float - julian day standard says .00 is midday, 12:00 pm.

Note

Normal pike (ie, 32 bit) floats (without --with-double-precision) has a limit of about 7 digits, and since we are about julian day 2500000, the precision on time of day is very limited.


Methodminute
Methodminutes
Methodnumber_of_minutes

Minute minute()
Minute minute(intn)
array(Minute) minutes()
array(Minute) minutes(intfirst, intlast)
intnumber_of_minutes()

Description

minute() gives back the timerange representing the first or nth Minute of the called object. Note that minutes normally starts to count at zero, so ->minute(2) gives the third minute within the range.

An Minute is in the Calendar perspective as any other time range not only 60 seconds, but also one of the (normally) 60 minutes of the Hour, precisely.

minutes() give back an array of all the minutes containing the time periods called. With arguments, it will give back a range of those minutes, in the same enumeration as the n to minute().

number_of_minutes() simple counts the number of minutes containing the called time period.


Methodmove_seconds
Methodmove_ns

TimeRange move_seconds(intseconds)
TimeRange move_ns(intnanoseconds)

Description

These two methods gives back the time range called moved the specified amount of time, with the length intact.

The motion is relative to the original position in time; 10 seconds ahead of 10:42:32 is 10:42:42, etc.


Methodsecond
Methodseconds
Methodnumber_of_seconds

Second second()
Second second(intn)
array(Second) seconds()
array(Second) seconds(intfirst, intlast)
intnumber_of_seconds()

Description

second() gives back the timerange representing the first or nth Second of the called object. Note that seconds normally starts to count at zero, so ->second(2) gives the third second within the range.

seconds() give back an array of all the seconds containing the time periods called. With arguments, it will give back a range of those seconds, in the same enumeration as the n to second().

number_of_seconds() simple counts the number of seconds containing the called time period.


Methodset_size_seconds
Methodset_size_ns

TimeRange set_size_seconds(intseconds)
TimeRange set_size_ns(intnanoseconds)

Description

These two methods allows the time range to be edited by size of specific units.


Methodunix_time

intunix_time()

Description

This calculates the corresponding unix time, - as returned from time(2) - from the time range. Note that the calculated unix time is the beginning of the period.

Module Calendar.TimeRanges

Class Calendar.TimeRanges.TimeRange

Description

This is the base class (usually implemented by e.g. Calendar subclasses like Calendar.Second) for any time measurement and calendrar information. It defines all the things you can do with a time range or any time period.

A TimeRange doubles as both a fixed period in time, and an amount of time. For instance, a week plus a day moves the week-period one day ahead (unaligning it with the week period, and thereby reducing it to just 7 days), no matter when in time the actual day were.


Method`==
Method_equal

bool res = Calendar.TimeRanges.TimeRange() == compared_to
boolequal(Calendar.TimeRanges.TimeRangefrom, TimeRangecompared_to)

Description

These two overloads the operator `== and the result of the equal function.

a==b is considered true if the two timeranges are of the same type, have the same rules (language, timezone, etc) and are the same timerange.

equal(a,b) are considered true if a and b are the same timerange, exactly the same as the equals method.

The __hash method is also present, to make timeranges possible to use as keys in mappings.

known bugs: _equal is not currently possible to overload, due to weird bugs, so equal uses `== for now.


Method`&

TimeRange res = Calendar.TimeRanges.TimeRange() & with

Description

Gives the cut on the called time period with another time period. The result is zero if the two periods doesn't overlap.

>- the past          the future -<
 |-------called-------|
      |-------other--------|
      >----- cut -----<
 

Method`*

TimeRange res = Calendar.TimeRanges.TimeRange() * n

Description

This changes the amount of time in the time period. t*17 is the same as doing t->set_size(t,17).


Method`+
Method`-

TimeRange res = Calendar.TimeRanges.TimeRange() + n
TimeRange res = Calendar.TimeRanges.TimeRange() + offset
TimeRange res = Calendar.TimeRanges.TimeRange() - m
TimeRange res = Calendar.TimeRanges.TimeRange() - x

Description

This calculates the (promoted) time period either n step away or with a given offset. These functions does use add to really do the job:

t+n         t->add(n)             t is a time period
t-n         t->add(-n)            offset is a time period
t+offset    t->add(1,offset)      n is an integer
t-offset    t->add(-1,offset)
n+t         t->add(n)
n-t         illegal
offset+t    offset->add(1,t)      | note this!
offset-t    offset->add(-1,t)     |

Mathematic rules:

x+(t-x) == t    x is an integer or a time period
(x+t)-x == t    t is a time period
(t+x)-x == t
o-(o-t) == t    o is a time period
t++ == t+1
t-- == t-1
Note

a-b does not give the distance between the start of a and b. Use the distance() function to calculate that.

The integer used to `+, `- and add are the number of steps the motion will be. It does never represent any fixed amount of time, like seconds or days.


Method`/
Methodsplit

array(TimeRange) res = Calendar.TimeRanges.TimeRange() / n
array(TimeRange) split(int|floatn, objectvoid|TimeRangewith)

Description

This divides the called timerange into n pieces. The returned timerange type is not necessarily of the same type as the called one. If the optional timerange is specified then the resulting timeranges will be multiples of that range (except for the last one).

known bugs: These are currently not defined for supertimeranges.


Method`/
Methodhow_many

int res = Calendar.TimeRanges.TimeRange() / with
inthow_many(TimeRangewith)

Description

This calculates how many instances of the given timerange has passed during the called timerange.

For instance, to figure out your age, create the timerange of your lifespan, and divide with the instance of a Year.


Method`<
Method`>

bool res = Calendar.TimeRanges.TimeRange() < compared_to
bool res = Calendar.TimeRanges.TimeRange() > compared_to

Description

These operators sorts roughty on the periods place in time. The major use might be to get multiset to work, besides sorting events clearly defined in time.


Method`^

TimeRange res = Calendar.TimeRanges.TimeRange() ^ with

Description

Gives the exclusive-or on the called time period and another time period, ie the union without the cut. The result is zero if the two periods were the same.

>- the past          the future -<
 |-------called-------|
      |-------other--------|
 <----|               |---->   - exclusive or
 

Method`|

TimeRange res = Calendar.TimeRanges.TimeRange() | with

Description

Gives the union on the called time period and another time period.

>- the past          the future -<
 |-------called-------|
      |-------other--------|
 <----------union---------->
 

Methodadd

TimeRange add(intn, void|TimeRangestep)

Description

calculates the (promoted) time period n steps away; if no step is given, the step's length is of the same length as the called time period.

It is not recommended to loop by adding the increment time period to a shorter period; this can cause faults, if the shorter time period doesn't exist in the incremented period. (Like week 53, day 31 of a month or the leap day of a year.)

Recommended use are like this:

   // loop over the 5th of the next 10 months
   TimeRange month=Month()+1;
   TimeRange orig_day=month()->day(5);
   for (int i=0; i<10; i++)
   {
      month++;
      TimeRange day=month->place(orig_day);
      <i>...use day...</i>
   }

Methodbeginning
Methodend

TimeRange beginning()
TimeRange end()

Description

This gives back the zero-sized beginning or end of the called time period.

rule: range(t->beginning(),t->end())==t


Methodcalendar

Calendar calendar()

Description

Simply gives back the calendar in use, for instance Calendar.ISO or Calendar.Discordian.


Methodstrictly_preceeds
Methodpreceeds
Methodis_previous_to
Methodoverlaps
Methodcontains
Methodequals
Methodis_next_to
Methodsucceeds
Methodstrictly_succeeds

boolstrictly_preceeds(TimeRangewhat)
boolpreceeds(TimeRangewhat)
boolis_previous_to(TimeRangewhat)
booloverlaps(TimeRangewhat)
boolcontains(TimeRangewhat)
boolequals(TimeRangewhat)
boolis_next_to(TimeRangewhat)
boolsucceeds(TimeRangewhat)
boolstrictly_succeeds(TimeRangewhat)

Description

These methods exists to compare two periods of time on the timeline.

          case            predicates
 
 <-- past       future ->
 
 |----A----|              A strictly preceeds B,
              |----B----| A preceeds B
 
 |----A----|              A strictly preceeds B, A preceeds B,
           |----B----|    A is previous to B, A touches B
 
     |----A----|          A preceeds B,
           |----B----|    A overlaps B, A touches B
 
     |-------A-------|    A preceeds B, A ends with B
           |----B----|    A overlaps B, A contains B, A touches B,
 
     |-------A-------|    A preceeds B,  A succeeds B,
         |---B---|        A overlaps B, A contains B, A touches B
 
        |----A----|       A overlaps B, A touches B, A contains B
        |----B----|       A equals B, A starts with B, A ends with B
 
     |-------A-------|    A succeeds B, A starts with B
     |----B----|          A overlaps B, A contains B, A touches B
 
           |----A----|    A succeeds B,
     |----B----|          A overlaps B, A touches B
 
           |----A----|    A strictly succeeds B, A succeeds B
 |----B----|              A is next to B, A touches B
 
             |----A----|  A strictly succeeds B,
 |----B----|              A succeeds B
 
 
Note

These methods only check the range of the first to the last time in the period; use of combined time periods (SuperTimeRanges) might not give you the result you want.

See also

`&amp;


Methodcreate

Calendar.TimeRanges.TimeRangeCalendar.TimeRanges.TimeRange(TimeRangefrom)

Description

Create the timerange from another timerange.

This is useful when converting objects from one calendar to another. Note that the ruleset will be transferred to the new object, so this method can't be used to convert between timezones or languges - use set_timezone, set_language or set_ruleset to achieve this.

Note

The size of the new object may be inexact; a Month object can't comprehend seconds, for instance.


Methodcreate

Calendar.TimeRanges.TimeRangeCalendar.TimeRanges.TimeRange("julian", int|floatjulian_day)

Description

Create the timerange from a julian day, the standardized method of counting days. If the timerange is more then a day, it will at least enclose the day.


Methodcreate

Calendar.TimeRanges.TimeRangeCalendar.TimeRanges.TimeRange("unix", intunixtime)
Calendar.TimeRanges.TimeRangeCalendar.TimeRanges.TimeRange("unix", intunixtime, intseconds_len)

Description

Create the timerange from unix time (as given by time(2)), with eventually the size of the time range in the same unit, seconds.


Methodrange
Methodspace
Methoddistance

TimeRange range(TimeRangeother)
TimeRange space(TimeRangeother)
TimeRange distance(TimeRangeother)

Description

Derives different time periods in between the called timerange and the parameter timerange.

>- the past          the future -<
 |--called--|         |--other--|
 >------------ range -----------<
            >--space--<
 >----- distance -----<
 

See also: add, TimeRanges.range, TimeRanges.space, TimeRanges.distance


Methodset_language
Methodlanguage

TimeRange set_language(Rule.Languagelang)
TimeRange set_language(stringlang)
Language language()

Description

Set or get the current language rule.


Methodnext
Methodprev

TimeRange next()
TimeRange prev()

Description

Next and prev are compatible and convinience functions; a->next() is exactly the same as a+1; a=a->next() is a++.


Methodoffset_to

intoffset_to(TimeRangex)

Description

Calculates offset to x; this compares two timeranges and gives the integer offset between the two starting points.

This is true for suitable a and b: a+a->offset_to(b)==b

By suitable means that a and b are of the same type and size. This is obviously true only if a+n has b as a possible result for any n.


Methodplace

TimeRange place(TimeRangethis)
TimeRange place(TimeRangethis, boolforce)

Description

This will place the given timerange in this timerange, for instance, day 37 in the year - Year(1934)->place(Day(1948 d37)) => Day(1934 d37).

Note

The rules how to place things in different timeranges can be somewhat 'dwim'.


Methodset_ruleset
Methodruleset

TimeRange set_ruleset(Rulesetr)
TimeRange ruleset(Rulesetr)

Description

Set or get the current ruleset.

Note

this may include timezone shanges, and change the time of day.


Methodset_size

TimeRange set_size(TimeRangesize)
TimeRange set_size(intn, TimeRangesize)

Description

Gives back a new (or the same, if the size matches) timerange with the new size. If n are given, the resulting size will be n amounts of the given size.

Note

A negative size is not permitted; a zero one are.


Methodset_timezone
Methodtimezone

TimeRange set_timezone(Timezonetz)
TimeRange set_timezone(stringtz)
TimeZone timezone()

Description

Set or get the current timezone (including dst) rule.

Note

The time-of-day may very well change when you change timezone.

To get the time of day for a specified timezone, select the timezone before getting the time of day:

Year(2003)->...->set_timezone(TimeZone.CET)->...->hour(14)->...


Methodsubtract

TimeRange subtract(TimeRangewhat)

Description

This subtracts a period of time from another;

>- the past          the future -<
|-------called-------|
     |-------other--------|
<---->  <- called->subtract(other)
 
|-------called-------|
     |---third---|
<---->           <---> <- called->subtract(third)

Module Calendar.Timezone

Description

This module contains all the predefined timezones. Index it with whatever timezone you want to use.

Example: Calendar.Calendar my_cal= Calendar.ISO->set_timezone(Calendar.Timezone["Europe/Stockholm"]);

A simpler way of selecting timezones might be to just give the string to set_timezone; it indexes by itself:

Calendar.Calendar my_cal= Calendar.ISO->set_timezone("Europe/Stockholm");

Note

Do not confuse this module with Ruleset.Timezone, which is the base class of a timezone object.

"CET" and some other standard abbreviations work too, but not all of them (due to more then one country using them).

Do not call set_timezone too often, but remember the result if possible. It might take some time to initialize a timezone object.

There are about 504 timezones with 127 different daylight saving rules. Most of them historic.

The timezone information comes from ftp://elsie.nci.nih.gov/pub/ and are not made up from scratch. Timezone bugs may be reported to the timezone mailing list, tz@elsie.nci.nih.gov, preferable with a cc to mirar+pike@mirar.org. /Mirar

See also

TZnames


Constantlocale

constant Calendar.Timezone.locale = Rule.Timezone

Description

This contains the local timezone, found from various parts of the system, if possible.


Constantlocaltime

constant Calendar.Timezone.localtime = Rule.Timezone

Description

This is a special timezone, that uses localtime() and tzname to find out what current offset and timezone string to use.

locale uses this if there is no other way of finding a better timezone to use.

This timezone is limited by localtime and libc to the range of time_t, which is a MAXINT on most systems - 13 Dec 1901 20:45:52 to 19 Jan 2038 3:14:07, UTC.

Module Calendar.YMD

Description

base for all Roman-kind of Calendars, ie, one with years, months, weeks and days


InheritTime

inherit Time : Time


Methoddatetime

mapping(string:int) datetime(int|voidunix_time)

Description

Replacement for localtime; gives back a mapping:

 ([ "year":     int        // year number (2000 AD=2000, 1 BC==0)
    "month":    int(1..)   // month of year
    "day":      int(1..)   // day of month
    "yearday":  int(1..)   // day of year
    "week":     int(1..)   // week of year
    "week_day": int(1..)   // day of week (depending on calendar)
    "unix":     int        // unix time
    "julian":   float      // julian day
    "hour":     int(0..)   // hour of day, including dst
    "minute":   int(0..59) // minute of hour
    "second":   int(0..59) // second of minute
    "fraction": float      // fraction of second
    "timezone": int        // offset to utc, including dst
 ]);
This is the same as calling Second()->datetime().

Methoddatetime_name
Methoddatetime_short_name

stringdatetime_name(int|voidunix_time)
stringdatetime_short_name(int|voidunix_time)

Description

Compat functions; same as format_iso and format_iso_short.


Methoddeltat

floatdeltat(intunadjusted_utc)

Description

Terrestrial Dynamical Time difference from standard time.

An approximation of the difference between TDT and UTC in fractional seconds at the specified time.

The zero point is 1901-06-25T14:23:01 UTC (unix time -2162281019), ie the accumulated number of leap seconds since then is returned.

Returns
Note

The function is based on polynomials provided by NASA, and the result may differ from actual for dates after 2004.


Methoddwim_day

Day dwim_day(stringdate)
Day dwim_day(stringdate, TimeRangecontext)

Description

Tries a number of different formats on the given date (in order):

<ref>parse</ref> format                  as in
"%y-%M-%D (%M) -W%W-%e (%e)"  "2000-03-20 (Mar) -W12-1 (Mon)"
"%y-%M-%D"                    "2000-03-20", "00-03-20"
"%M%/%D/%y"                   "3/20/2000"
"%D%*[ /]%M%*[ /-,]%y"        "20/3/2000" "20 mar 2000" "20/3 -00"
"%e%*[ ]%D%*[ /]%M%*[ /-,]%y" "Mon 20 Mar 2000" "Mon 20/3 2000"
"-%y%*[ /]%D%*[ /]%M"         "-00 20/3" "-00 20 mar"
"-%y%*[ /]%M%*[ /]%D"         "-00 3/20" "-00 march 20"
"%y%*[ /]%D%*[ /]%M"          "00 20 mar" "2000 20/3"
"%y%*[ /]%M%*[ /]%D"          "2000 march 20"
"%D%.%M.%y"                   "20.3.2000"
"%D%*[ -/]%M"                 "20/3" "20 mar" "20-03"
"%M%*[ -/]%D"                 "3/20" "march 20"
"%M-%D-%y"                    "03-20-2000"
"%D-%M-%y"                    "20-03-2000"
"%e%*[- /]%D%*[- /]%M"        "mon 20 march"
"%e%*[- /]%M%*[- /]%D"        "mon/march/20"
"%e%*[ -/wv]%W%*[ -/]%y"      "mon w12 -00" "1 w12 2000"
"%e%*[ -/wv]%W"               "mon w12"
"%d"                          "20000320", "000320"
"today"                       "today"
"last %e"                     "last monday"
"next %e"                     "next monday"
Note

Casts exception if it fails to dwim out a day. "dwim" means do-what-i-mean.


Methoddwim_time

Day dwim_time(stringdate_time)
Day dwim_time(stringdate_time, objectTimeRangecontext)

Description

Tries a number of different formats on the given date_time.

Note

Casts exception if it fails to dwim out a time. "dwim" means do-what-i-mean.


Methodformat_iso
Methodformat_iso_short
Methodformat_iso_tod
Methodformat_day_iso
Methodformat_day_iso_short

stringformat_iso(void|intunix_time)
stringformat_iso_short(void|intunix_time)
stringformat_iso_tod(void|intunix_time)
stringformat_day_iso(void|intunix_time)
stringformat_day_iso_short(void|intunix_time)

Description

Format the object into nice strings;

iso    "2000-06-02 (Jun) -W22-5 (Fri) 11:57:18 CEST"
iso_short   "2000-06-02 11:57:18"
iso_tod     "11:57:18"

Methodparse

TimeRange parse(stringfmt, stringarg)

Description

parse a date, create relevant object fmt is in the format "abc%xdef..." where abc and def is matched, and %x is one of those time units:

%Y absolute year
%y dwim year (70-99 is 1970-1999, 0-69 is 2000-2069)
%M month (number, name or short name) (needs %y)
%W week (needs %y)
%D date (needs %y, %m)
%d short date (20000304, 000304)
%a day (needs %y)
%e weekday (needs %y, %w)
%h hour (needs %d, %D or %W)
%m minute (needs %h)
%s second (needs %m)
%S seconds since the Epoch (only combines with %f)
%f fraction of a second (needs %s or %S)
%t short time (205314, 2053)
%z zone
%p "am" or "pm"
%n empty string (to be put at the end of formats)
Returns

0 if format doesn't match data, or the appropriate time object.

Note

The zone will be a guess if it doesn't state an exact regional timezone (like "Europe/Stockholm") - most zone abbriviations (like "CET") are used by more then one region with it's own daylight saving rules. Also beware that for instance CST can be up to four different zones, central Australia or America being the most common.

Abbreviation Interpretation
AMT          America/Manaus       [UTC-4]
AST          America/Curacao      [UTC-4]
CDT          America/Costa_Rica   [UTC-6]
CST          America/El Salvador  [UTC-6]
EST          America/Panama       [UTC-5]
GST          Asia/Dubai           [UTC+4]
IST          Asia/Jerusalem       [UTC+2]
WST          Australia/Perth      [UTC+8]

This mapping is modifiable in the ruleset, see Ruleset.set_abbr2zone.

Class Calendar.YMD.Day


InheritYMD

inherit YMD : YMD


Methodcreate

Calendar.YMD.DayCalendar.YMD.Day("unix", intunix_time)
Calendar.YMD.DayCalendar.YMD.Day("julian", int|floatjulian_day)
Calendar.YMD.DayCalendar.YMD.Day(intyear, intmonth, intday)
Calendar.YMD.DayCalendar.YMD.Day(intyear, intyear_day)
Calendar.YMD.DayCalendar.YMD.Day(intjulian_day)

Description

It's possible to create the day by using five different methods; either the normal way - from standard unix time or the julian day, and also, for more practical use, from year, month and day, from year and day of year, and from julian day without extra fuzz.

Class Calendar.YMD.Fraction


InheritFraction

inherit Time.Fraction : Fraction


InheritYMD

inherit YMD : YMD

Class Calendar.YMD.Hour


InheritHour

inherit Time.Hour : Hour


InheritYMD

inherit YMD : YMD

Class Calendar.YMD.Minute


InheritMinute

inherit Time.Minute : Minute


InheritYMD

inherit YMD : YMD

Class Calendar.YMD.Month


InheritYMD

inherit YMD : YMD

Class Calendar.YMD.Second


InheritSecond

inherit Time.Second : Second


InheritYMD

inherit YMD : YMD

Class Calendar.YMD.SuperTimeRange


InheritSuperTimeRange

inherit Time.SuperTimeRange : SuperTimeRange

Class Calendar.YMD.Week

Description

The Calendar week represents a standard time period of a week. In the Gregorian calendar, the standard week starts on a sunday and ends on a saturday; in the ISO calendar, it starts on a monday and ends on a sunday.

The week are might not be aligned to the year, and thus the week may cross year borders and the year of the week might not be the same as the year of all the days in the week. The basic rule is that the week year is the year that has the most days in the week, but since week number only is specified in the ISO calendar - and derivates - the week number of most calendars is the week number of most of the days in the ISO calendar, which modifies this rule for the Gregorian calendar; the week number and year is the same as for the ISO calendar, except for the sundays.

When adding, moving and subtracting months to a week, it falls back to using days.

When adding, moving or subtracting years, if tries to place the moved week in the resulting year.


InheritYMD

inherit YMD : YMD


Methodcreate

Calendar.YMD.WeekCalendar.YMD.Week("unix", intunix_time)
Calendar.YMD.WeekCalendar.YMD.Week("julian", int|floatjulian_day)
Calendar.YMD.WeekCalendar.YMD.Week(intyear, intweek)

Description

It's possible to create the standard week by using three different methods; either the normal way - from standard unix time or the julian day, and also, for more practical use, from year and week number.

Can be less than 1 for the first week of the year if it begins in the previous year.


Methodday

Day day()
Day day(intn)
Day day(stringname)

Description

The Week type overloads the day() method, so it is possible to get a specified weekday by string:

week->day("sunday")

The integer and no argument behavior is inherited from YMD().

Note

the weekday-from-string routine is language dependent.

Class Calendar.YMD.YMD

Description

Base (virtual) time period of the Roman-kind of calendar.


InheritTimeRange

inherit TimeRange : TimeRange


Methoddatetime

mappingdatetime()

Description

This gives back a mapping with the relevant time information (representing the start of the period);

 ([ "year":     int        // year number (2000 AD=2000, 1 BC==0)
    "month":    int(1..)   // month of year
    "day":      int(1..)   // day of month
    "yearday":  int(0..)   // day of year
    "week":     int(1..)   // week of year
    "week_day": int(0..)   // day of week
    "timezone": int        // offset to utc, including dst
 
    "unix":     int        // unix time
    "julian":   int        // julian day
 // for compatibility:
    "hour":     0          // hour of day, including dst
    "minute":   0          // minute of hour
    "second":   0          // second of minute
    "fraction": 0.0        // fraction of second
 ]);
Note

Day of week is compatible with old versions, ie, 0 is sunday, 6 is saturday, so it shouldn't be used to calculate the day of the week with the given week number. Year day is also backwards compatible, ie, one (1) less then from the year_day() function.

If this function is called in a Week object that begins with the first week of a year, it returns the previous year if that is where the week starts. To keep the representation unambiguous, the returned week number is then one more than the number of weeks in that year.

E.g. Week(2008,1)->datetime() will return year 2007 and week 53 since the first week of 2008 starts in 2007.


Methodday

Day day()
Day day(intn)

Description

Get day number n in the current range.

If n is negative, it is counted from the end of the range.


Methoddays

array(Day) days(int|voidfrom, objectint|voidto)

Description

Get the days in the current range.


Methodformat_iso_ymd
Methodformat_ymd
Methodformat_ymd_short
Methodformat_ymd_xshort
Methodformat_mdy
Methodformat_iso_week
Methodformat_iso_week_short
Methodformat_week
Methodformat_week_short
Methodformat_month
Methodformat_month_short
Methodformat_iso_time
Methodformat_time
Methodformat_time_short
Methodformat_time_xshort
Methodformat_mtime
Methodformat_xtime
Methodformat_tod
Methodformat_todz
Methodformat_xtod
Methodformat_mod

stringformat_iso_ymd()
stringformat_ymd()
stringformat_ymd_short()
stringformat_ymd_xshort()
stringformat_mdy()
stringformat_iso_week()
stringformat_iso_week_short()
stringformat_week()
stringformat_week_short()
stringformat_month()
stringformat_month_short()
stringformat_iso_time()
stringformat_time()
stringformat_time_short()
stringformat_time_xshort()
stringformat_mtime()
stringformat_xtime()
stringformat_tod()
stringformat_todz()
stringformat_xtod()
stringformat_mod()

Description

Format the object into nice strings;

iso_ymd        "2000-06-02 (Jun) -W22-5 (Fri)" [2]
ext_ymd        "Friday, 2 June 2000" [2]
ymd            "2000-06-02"
ymd_short      "20000602"
ymd_xshort     "000602" [1]
iso_week       "2000-W22"
iso_week_short "2000W22"
week           "2000-w22" [2]
week_short     "2000w22" [2]
month          "2000-06"
month_short    "200006" [1]
iso_time       "2000-06-02 (Jun) -W22-5 (Fri) 00:00:00 UTC+1" [2]
ext_time       "Friday, 2 June 2000, 00:00:00" [2]
ctime          "Fri Jun  2 00:00:00 2000\n" [2] [3]
http           "Fri, 02 Jun 2000 00:00:00 GMT" [4]
time           "2000-06-02 00:00:00"
time_short     "20000602 00:00:00"
time_xshort    "000602 00:00:00"
iso_short      "2000-06-02T00:00:00"
mtime          "2000-06-02 00:00"
xtime          "2000-06-02 00:00:00.000000"
tod            "00:00:00"
tod_short      "000000"
todz           "00:00:00 CET"
todz_iso       "00:00:00 UTC+1"
xtod           "00:00:00.000000"
mod            "00:00"
[1] note conflict (think 1 February 2003)
[2] language dependent
[3] as from the libc function ctime()
[4] as specified by the HTTP standard; not language dependent.

The iso variants aim to be compliant with ISO-8601.


Methodfraction_no
Methodhour_no
Methodjulian_day
Methodleap_year
Methodminute_no
Methodmonth_day
Methodmonth_days
Methodmonth_no
Methodsecond_no
Methodutc_offset
Methodweek_day
Methodweek_no
Methodyear_day
Methodyear_no
Methodmonth_name
Methodmonth_shortname
Methodmonth_day_name
Methodweek_day_name
Methodweek_day_shortname
Methodweek_name
Methodyear_name
Methodtzname
Methodtzname_iso
Methodunix_time

floatfraction_no()
inthour_no()
intjulian_day()
intleap_year()
intminute_no()
intmonth_day()
intmonth_days()
intmonth_no()
intsecond_no()
intutc_offset()
intweek_day()
intweek_no()
intyear_day()
intyear_no()
stringmonth_name()
stringmonth_shortname()
stringmonth_day_name()
stringweek_day_name()
stringweek_day_shortname()
stringweek_name()
stringyear_name()
stringtzname()
stringtzname_iso()
intunix_time()

Description

Returns the unix time integer corresponding to the start of the time range object. (An unix time integer is UTC.)


Methodsecond
Methodminute
Methodseconds
Methodnumber_of_seconds
Methodminutes
Methodnumber_of_minutes
Methodhour
Methodhours
Methodnumber_of_hours

Second second()
Second second(intn)
Minute minute(inthour, intminute, intsecond)
array(Second) seconds()
array(Second) seconds(intfirst, intlast)
intnumber_of_seconds()
Minute minute()
Minute minute(intn)
Minute minute(inthour, intminute)
array(Minute) minutes()
array(Minute) minutes(intfirst, intlast)
intnumber_of_minutes()
Hour hour()
Hour hour(intn)
array(Hour) hours()
array(Hour) hours(intfirst, intlast)
intnumber_of_hours()


Methodnumber_of_days

intnumber_of_days()

Description

Get the number of days in the current range.

Class Calendar.YMD.Year

Description

This is the time period of a year.


InheritTimeRange

inherit TimeRange : TimeRange


InheritYMD

inherit YMD : YMD


Methodcreate

Calendar.YMD.YearCalendar.YMD.Year("unix", intunix_time)
Calendar.YMD.YearCalendar.YMD.Year("julian", int|floatjulian_day)
Calendar.YMD.YearCalendar.YMD.Year(intyear)
Calendar.YMD.YearCalendar.YMD.Year(stringyear)
Calendar.YMD.YearCalendar.YMD.Year(TimeRangerange)

Description

It's possible to create the standard year by using three different methods; either the normal way - from standard unix time or the julian day, and also, for more practical use, from the year number.


Methodmonth

Month month()
Month month(intn)
Month month(stringname)

Description

The Year type overloads the month() method, so it is possible to get a specified month by string:

year->month("April")

The integer and no argument behavior is inherited from YMD().


Methodweek

Week week()
Week week(intn)
Week week(stringname)

Description

The Year type overloads the week() method, so it is possible to get a specified week by name:

year->week("17")year->week("w17")

The integer and no argument behavior is inherited from YMD().

This is useful, since the first week of a year not always (about half the years, in the ISO calendar) is numbered '1'.

Module Calendar.default_rules

Description

This is the default ruleset (which is ISO).


InheritRuleset

inherit Ruleset : Ruleset