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.


Constant nulltimerange

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.


Method now

Calendar.TimeRanges.TimeRange now()

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


Method clone

this_program clone()


Method set_abbr2zone

this_program set_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


Method set_language

this_program set_language(string|Calendar.Rule.Language lang)


Method set_rule

this_program set_rule(Calendar.Rule.Language|Calendar.Rule.Timezone rule)


Method set_timezone

this_program set_timezone(string|Calendar.Rule.Timezone t)

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.


Method create

Calendar.SuperTimeRange Calendar.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.


Inherit TimeRange

inherit TimeRange : TimeRange

Module Calendar.Austrian

Description

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

This calendar exist only for backwards compatible purposes.


Inherit ISO

inherit Calendar.ISO : ISO

Module Calendar.Badi

Description

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


Method daystart_offset

int daystart_offset()

Description

Returns the offset to the start of the time range object


Inherit YMD

inherit Calendar.YMD : YMD

Class Calendar.Badi.Vahid


Inherit YMD

inherit YMD : YMD


Method year

Year year()
Year year(int n)
Year year(string name)

Description

Return a year in the vahid by number or name:

vahid->year("Alif")

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.


Inherit Gregorian

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.


Inherit Gregorian

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.


Method create

Calendar.Event.Date Calendar.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).


Inherit Day_Event

inherit Day_Event : Day_Event

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.


Method create

Calendar.Event.Date_Weekday Calendar.Event.Date_Weekday(int month_day, int month, int weekday)

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.


Inherit Day_Event

inherit Day_Event : Day_Event

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.


Constant NODAY

constant int Calendar.Event.Day_Event.NODAY

Description

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


Inherit Event

inherit Event : Event


Constant is_day_event

constant int Calendar.Event.Day_Event.is_day_event

Description

This constant may be used to identify Day_Event objects.


Method next

Calendar.TimeRanges.TimeRange next(void|Calendar.TimeRanges.TimeRange from, void|bool including)

Description

Uses the virtual method scan_jd.

See also

Event.next


Method previous

Calendar.TimeRanges.TimeRange|zero previous(void|Calendar.TimeRanges.TimeRange from, void|bool including)

Description

Uses the virtual method scan_jd.

See also

Event.previous


Method scan_jd

int scan_jd(Calendar.Calendar realm, int jd, int(-1..-1)|int(1..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.


Method create

Calendar.Event.Easter Calendar.Event.Easter(void|int shift)

Description

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


Method easter_yd

int easter_yd(int y, int yjd, int leap)

Description

Calculates the year day for the easter.


Inherit Day_Event

inherit Day_Event : Day_Event

Class Calendar.Event.Easter_Relative

Description

This class represents an easter relative event.


Method create

Calendar.Event.Easter_Relative Calendar.Event.Easter_Relative(string id, string name, int offset)


Inherit Easter

inherit Easter : Easter

Class Calendar.Event.Event

Description

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


Method `|
Method ``|

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

Description

Joins several events into one SuperEvent.


Method describe

string describe()

Description

Returns a description of the event.


Constant is_event

constant int Calendar.Event.Event.is_event

Description

This constant may be used to identify an event object.


Method next
Method previous

Calendar.TimeRanges.TimeRange next(void|Calendar.TimeRanges.TimeRange from, void|bool including)
Calendar.TimeRanges.TimeRange previous(void|Calendar.TimeRanges.TimeRange from, void|bool including)

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.


Method scan

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

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.


Method scan_events

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

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


Method create

Calendar.Event.Gregorian_Fixed Calendar.Event.Gregorian_Fixed(string id, string name, int(1..31) month_day, int(1..12) month, int extra)


Inherit Day_Event

inherit Day_Event : Day_Event


Constant is_fixed

constant int Calendar.Event.Gregorian_Fixed.is_fixed

Description

This constant may be used to identify Gregorian_Fixed objects.

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


Inherit Gregorian_Fixed

inherit Gregorian_Fixed : Gregorian_Fixed


Constant is_julian_fixed

constant int 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.


Method create

Calendar.Event.Monthday_Weekday Calendar.Event.Monthday_Weekday(int month_day, int weekday)

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.


Inherit Day_Event

inherit Day_Event : Day_Event

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


Method create

Calendar.Event.Monthday_Weekday_Relative Calendar.Event.Monthday_Weekday_Relative(string id, string name, int(1..31) md, int(1..12) mn, int(1..7) _wd, int _n, void|bool _inclusive)


Inherit Gregorian_Fixed

inherit Gregorian_Fixed : Gregorian_Fixed

Class Calendar.Event.Nameday

Description

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


Inherit Day_Event

inherit Day_Event : Day_Event


Constant is_nameday

constant int 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.


Inherit Event

inherit Event : Event


Constant is_namedays

constant int Calendar.Event.Namedays.is_namedays

Description

This constant may be used to identify Namedays.


Method namedays

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

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.


Method names

array(string) names(Calendar.TimeRanges.TimeRange t)

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.


Inherit Event

inherit Event : Event


Constant is_nullevent

constant int 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.


Method create

Calendar.Event.Orthodox_Easter_Relative Calendar.Event.Orthodox_Easter_Relative(string id, string name, int offset)


Inherit Easter_Relative

inherit Easter_Relative : Easter_Relative

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.


Method create

Calendar.Event.Solar Calendar.Event.Solar(int|void event_type)


Variable event_type

int|void Calendar.Event.Solar.event_type


Inherit Day_Event

inherit Day_Event : Day_Event


Constant periodic_table

protected constant Calendar.Event.Solar.periodic_table

Description
Array
array(float) 0..
Array
float 0

Amplitude in days.

float 1

Cosine phase in radians in year 2000.

float 2

Period in radians/year.


Method previous

Calendar.TimeRanges.TimeRange previous(void|Calendar.TimeRanges.TimeRange from, void|bool including)

Description

Uses the virtual method scan_jd.

See also

Event.previous


Method scan_jd

int scan_jd(Calendar.Calendar realm, int jd, int(1..1)|int(-1..-1) direction)

Note

Returns unixtime in UTC to avoid losing the decimals!


Method solar_event

array(int|float) solar_event(int y)

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.


Method filter_flag
Method holidays
Method flagdays

SuperEvent filter_flag(string flag)
SuperEvent holidays()
SuperEvent flagdays()

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).


Inherit Event

inherit Event : Event

Class Calendar.Event.SuperNamedays

Description

Container for merged Namedays objects. Presumes non-overlapping namedays


Method create

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


Variable namedayss
Variable id

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


Inherit Event

inherit Event : Event

Class Calendar.Event.TZShift_Event

Description

Event containing information about when a timezone is changed.


Inherit Event

inherit Event : Event


Method scan_history

protected Calendar.TimeRanges.TimeRange scan_history(Calendar.Rule.Timezone tz, Calendar.TimeRanges.TimeRange from, int direction, bool including)


Method scan_rule

protected Calendar.TimeRanges.TimeRange|zero scan_rule(Calendar.Rule.Timezone tz, Calendar.TimeRanges.TimeRange from, int direction, int including)


Method scan_shift

protected Calendar.TimeRanges.TimeRange scan_shift(Calendar.Rule.Timezone tz, Calendar.TimeRanges.TimeRange from, int direction, int including)

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.


Method create

Calendar.Event.Weekday Calendar.Event.Weekday(int weekday, void|string id)

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.


Inherit Day_Event

inherit Day_Event : Day_Event

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 `[](string region)
Event.Event `->(string region)

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.


Inherit YMD

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.


Inherit Gregorian

inherit Calendar.Gregorian : Gregorian

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.


Inherit YMD

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.


Inherit Gregorian

inherit Calendar.Gregorian : Gregorian

Module Calendar.Rule

Class Calendar.Rule.Timezone

Description

Contains a time zone.


Method create

Calendar.Rule.Timezone Calendar.Rule.Timezone(int offset, string name)

Parameter offset

Offset to UTC, not counting DST.

Parameter name

The name of the time zone.


Method raw_utc_offset

int raw_utc_offset()

Description

Returns the offset to UTC, not counting DST.


Method tz_jd

array tz_jd(int julian_day)

FIXME

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


Method tz_ux

array tz_ux(int unixtime)

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.


Method now

cTick now()

Description

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

Class Calendar.Stardate.cTick


Method create

Calendar.Stardate.cTick Calendar.Stardate.cTick(mixed ... args)
Calendar.Stardate.cTick Calendar.Stardate.cTick(int|float date)
Calendar.Stardate.cTick Calendar.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)

Method format_long
Method format_short
Method format_vshort

string format_long(void|int precision)
string format_short(void|int precision)
string format_vshort(void|int precision)

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)


Inherit TimeRange

inherit Calendar.TimeRange : TimeRange


Method number_of_days

int number_of_days()

Description

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


Method number_of_seconds

int number_of_seconds()

Description

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


Method tic

float tic()

Description

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


Method tics

float tics()

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.


Inherit ISO

inherit Calendar.ISO : ISO

Module Calendar.TZnames

Description

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


Method _zone_tab
Method zone_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.


Constant abbr2zones

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.


Method zonenames

array(string) zonenames()

Description

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


Constant zones

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.

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).


Inherit TimeRanges

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.


Method create

Calendar.Time.Fraction Calendar.Time.Fraction()
Calendar.Time.Fraction Calendar.Time.Fraction("unix", int|float unixtime)
Calendar.Time.Fraction Calendar.Time.Fraction("unix", int|float unixtime, int|float len)
Calendar.Time.Fraction Calendar.Time.Fraction(int y, int m, int d, int h, int m, int s, int ns)

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.


Inherit Second

inherit Second : Second


Method now

TimeofDay now()

Description

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


Method set_ruleset
Method ruleset

Calendar set_ruleset(Ruleset r)
Ruleset ruleset()

Description

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


Method set_timezone
Method timezone

Calendar set_timezone(Timezone tz)
Calendar set_timezone(string|Timezone tz)
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


Inherit TimeofDay

inherit TimeofDay : TimeofDay

Class Calendar.Time.Minute


Inherit TimeofDay

inherit TimeofDay : TimeofDay

Class Calendar.Time.Second


Inherit TimeofDay

inherit TimeofDay : TimeofDay

Class Calendar.Time.SuperTimeRange


Method second
Method seconds
Method number_of_seconds
Method minute
Method minutes
Method number_of_minutes
Method hour
Method hours
Method number_of_hours

Second second()
Second second(int n)
array(Second) seconds()
array(Second) seconds(int first, int last)
int number_of_seconds()
Minute minute()
Minute minute(int n)
array(Minute) minutes()
array(Minute) minutes(int first, int last)
int number_of_minutes()
Hour hour()
Hour hour(int n)
array(Hour) hours()
array(Hour) hours(int first, int last)
int number_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.


Inherit SuperTimeRange

inherit TimeRanges.SuperTimeRange : SuperTimeRange

Class Calendar.Time.TimeofDay

Description

Virtual class used by e.g. Hour.


Method call_out

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

Description

Creates a call_out to this point in time.


Method create

Calendar.Time.TimeofDay Calendar.Time.TimeofDay()
Calendar.Time.TimeofDay Calendar.Time.TimeofDay(int unixtime)

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".


Method datetime

mapping datetime()

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
 ]);


Method format_iso_ymd
Method format_ymd
Method format_ymd_short
Method format_ymd_xshort
Method format_iso_week
Method format_iso_week_short
Method format_week
Method format_week_short
Method format_month
Method format_month_short
Method format_iso_time
Method format_time
Method format_time_short
Method format_iso_short
Method format_time_xshort
Method format_mtime
Method format_xtime
Method format_tod
Method format_xtod
Method format_mod
Method format_nice
Method format_nicez

string format_iso_ymd()
string format_ymd()
string format_ymd_short()
string format_ymd_xshort()
string format_iso_week()
string format_iso_week_short()
string format_week()
string format_week_short()
string format_month()
string format_month_short()
string format_iso_time()
string format_time()
string format_time_short()
string format_iso_short()
string format_time_xshort()
string format_mtime()
string format_xtime()
string format_tod()
string format_xtod()
string format_mod()
string format_nice()
string format_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


Method hour_no
Method minute_no
Method second_no
Method fraction_no

int hour_no()
int minute_no()
int second_no()
float fraction_no()

Description

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


Method hour
Method hours
Method number_of_hours

Hour hour()
Hour hour(int n)
array(Hour) hours()
array(Hour) hours(int first, int last)
int number_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)
            })
    


Inherit TimeRange

inherit TimeRange : TimeRange


Method julian_day

float julian_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.


Method minute
Method minutes
Method number_of_minutes

Minute minute()
Minute minute(int n)
array(Minute) minutes()
array(Minute) minutes(int first, int last)
int number_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.


Method move_seconds
Method move_ns

TimeRange move_seconds(int seconds)
TimeRange move_ns(int nanoseconds)

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.


Method second
Method seconds
Method number_of_seconds

Second second()
Second second(int n)
array(Second) seconds()
array(Second) seconds(int first, int last)
int number_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.


Method set_size_seconds
Method set_size_ns

TimeRange set_size_seconds(int seconds)
TimeRange set_size_ns(int nanoseconds)

Description

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


Method unix_time

int unix_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
bool equal(Calendar.TimeRanges.TimeRange from, TimeRange compared_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 `/
Method split

array(TimeRange) res = Calendar.TimeRanges.TimeRange() / n
array(TimeRange) split(int|float n, object void|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 `/
Method how_many

int res = Calendar.TimeRanges.TimeRange() / with
int how_many(TimeRange with)

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---------->
 


Method add

TimeRange add(int n, void|TimeRange step)

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>
   }


Method beginning
Method end

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


Method calendar

Calendar calendar()

Description

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


Method strictly_preceeds
Method preceeds
Method is_previous_to
Method overlaps
Method contains
Method equals
Method is_next_to
Method succeeds
Method strictly_succeeds

bool strictly_preceeds(TimeRange what)
bool preceeds(TimeRange what)
bool is_previous_to(TimeRange what)
bool overlaps(TimeRange what)
bool contains(TimeRange what)
bool equals(TimeRange what)
bool is_next_to(TimeRange what)
bool succeeds(TimeRange what)
bool strictly_succeeds(TimeRange what)

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;


Method create

Calendar.TimeRanges.TimeRange Calendar.TimeRanges.TimeRange(TimeRange from)

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.


Method create

Calendar.TimeRanges.TimeRange Calendar.TimeRanges.TimeRange("julian", int|float julian_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.


Method create

Calendar.TimeRanges.TimeRange Calendar.TimeRanges.TimeRange("unix", int unixtime)
Calendar.TimeRanges.TimeRange Calendar.TimeRanges.TimeRange("unix", int unixtime, int seconds_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.


Method range
Method space
Method distance

TimeRange range(TimeRange other)
TimeRange space(TimeRange other)
TimeRange distance(TimeRange other)

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


Method set_language
Method language

TimeRange set_language(Rule.Language lang)
TimeRange set_language(string lang)
Language language()

Description

Set or get the current language rule.


Method next
Method prev

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++.


Method offset_to

int offset_to(TimeRange x)

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.


Method place

TimeRange place(TimeRange this)
TimeRange place(TimeRange this, bool force)

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'.


Method set_ruleset
Method ruleset

TimeRange set_ruleset(Ruleset r)
TimeRange ruleset(Ruleset r)

Description

Set or get the current ruleset.

Note

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


Method set_size

TimeRange set_size(TimeRange size)
TimeRange set_size(int n, TimeRange size)

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.


Method set_timezone
Method timezone

TimeRange set_timezone(Timezone tz)
TimeRange set_timezone(string tz)
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)->...


Method subtract

TimeRange subtract(TimeRange what)

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


Constant locale

constant Calendar.Timezone.locale = Rule.Timezone

Description

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


Constant localtime

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


Method datetime

mapping(string:int) datetime(int|void unix_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().


Method datetime_name
Method datetime_short_name

string datetime_name(int|void unix_time)
string datetime_short_name(int|void unix_time)

Description

Compat functions; same as format_iso and format_iso_short.


Method deltat

float deltat(int unadjusted_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.


Method dwim_day

Day dwim_day(string date)
Day dwim_day(string date, TimeRange context)

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.


Method dwim_time

Day dwim_time(string date_time)
Day dwim_time(string date_time, object TimeRangecontext)

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.


Method format_iso
Method format_iso_short
Method format_iso_tod
Method format_day_iso
Method format_day_iso_short

string format_iso(void|int unix_time)
string format_iso_short(void|int unix_time)
string format_iso_tod(void|int unix_time)
string format_day_iso(void|int unix_time)
string format_day_iso_short(void|int unix_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"


Inherit Time

inherit Time : Time


Method parse

TimeRange parse(string fmt, string arg)

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


Method create

Calendar.YMD.Day Calendar.YMD.Day("unix", int unix_time)
Calendar.YMD.Day Calendar.YMD.Day("julian", int|float julian_day)
Calendar.YMD.Day Calendar.YMD.Day(int year, int month, int day)
Calendar.YMD.Day Calendar.YMD.Day(int year, int year_day)
Calendar.YMD.Day Calendar.YMD.Day(int julian_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.


Inherit YMD

inherit YMD : YMD

Class Calendar.YMD.Fraction


Inherit Fraction

inherit Time.Fraction : Fraction


Inherit YMD

inherit YMD : YMD

Class Calendar.YMD.Hour


Inherit Hour

inherit Time.Hour : Hour


Inherit YMD

inherit YMD : YMD

Class Calendar.YMD.Minute


Inherit Minute

inherit Time.Minute : Minute


Inherit YMD

inherit YMD : YMD

Class Calendar.YMD.Month


Inherit YMD

inherit YMD : YMD

Class Calendar.YMD.Second


Inherit Second

inherit Time.Second : Second


Inherit YMD

inherit YMD : YMD

Class Calendar.YMD.SuperTimeRange


Inherit SuperTimeRange

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.


Method create

Calendar.YMD.Week Calendar.YMD.Week("unix", int unix_time)
Calendar.YMD.Week Calendar.YMD.Week("julian", int|float julian_day)
Calendar.YMD.Week Calendar.YMD.Week(int year, int week)

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.


Method day

Day day()
Day day(int n)
Day day(string name)

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.


Inherit YMD

inherit YMD : YMD

Class Calendar.YMD.YMD

Description

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


Method datetime

mapping datetime()

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.


Method day

Day day()
Day day(int n)

Description

Get day number n in the current range.

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


Method days

array(Day) days(int|void from, object int|voidto)

Description

Get the days in the current range.


Method format_iso_ymd
Method format_ymd
Method format_ymd_short
Method format_ymd_xshort
Method format_mdy
Method format_iso_week
Method format_iso_week_short
Method format_week
Method format_week_short
Method format_month
Method format_month_short
Method format_iso_time
Method format_time
Method format_time_short
Method format_time_xshort
Method format_mtime
Method format_xtime
Method format_tod
Method format_todz
Method format_xtod
Method format_mod

string format_iso_ymd()
string format_ymd()
string format_ymd_short()
string format_ymd_xshort()
string format_mdy()
string format_iso_week()
string format_iso_week_short()
string format_week()
string format_week_short()
string format_month()
string format_month_short()
string format_iso_time()
string format_time()
string format_time_short()
string format_time_xshort()
string format_mtime()
string format_xtime()
string format_tod()
string format_todz()
string format_xtod()
string format_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.


Method fraction_no
Method hour_no
Method julian_day
Method leap_year
Method minute_no
Method month_day
Method month_days
Method month_no
Method second_no
Method utc_offset
Method week_day
Method week_no
Method year_day
Method year_no
Method month_name
Method month_shortname
Method month_day_name
Method week_day_name
Method week_day_shortname
Method week_name
Method year_name
Method tzname
Method tzname_iso
Method unix_time

float fraction_no()
int hour_no()
int julian_day()
int leap_year()
int minute_no()
int month_day()
int month_days()
int month_no()
int second_no()
int utc_offset()
int week_day()
int week_no()
int year_day()
int year_no()
string month_name()
string month_shortname()
string month_day_name()
string week_day_name()
string week_day_shortname()
string week_name()
string year_name()
string tzname()
string tzname_iso()
int unix_time()

Description

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


Method second
Method minute
Method seconds
Method number_of_seconds
Method minutes
Method number_of_minutes
Method hour
Method hours
Method number_of_hours

Second second()
Second second(int n)
Minute minute(int hour, int minute, int second)
array(Second) seconds()
array(Second) seconds(int first, int last)
int number_of_seconds()
Minute minute()
Minute minute(int n)
Minute minute(int hour, int minute)
array(Minute) minutes()
array(Minute) minutes(int first, int last)
int number_of_minutes()
Hour hour()
Hour hour(int n)
array(Hour) hours()
array(Hour) hours(int first, int last)
int number_of_hours()


Inherit TimeRange

inherit TimeRange : TimeRange


Method number_of_days

int number_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.


Method create

Calendar.YMD.Year Calendar.YMD.Year("unix", int unix_time)
Calendar.YMD.Year Calendar.YMD.Year("julian", int|float julian_day)
Calendar.YMD.Year Calendar.YMD.Year(int year)
Calendar.YMD.Year Calendar.YMD.Year(string year)
Calendar.YMD.Year Calendar.YMD.Year(TimeRange range)

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.


Inherit TimeRange

inherit TimeRange : TimeRange


Inherit YMD

inherit YMD : YMD


Method month

Month month()
Month month(int n)
Month month(string name)

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().


Method week

Week week()
Week week(int n)
Week week(string name)

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'.