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.
- Constantnulltimerange
constantCalendar.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.
Class Calendar.Ruleset
- Description
This is the container class for rules.
- Methodset_abbr2zone
this_programset_abbr2zone(mapping(string:string)abbr2zone)- Description
Sets the guess-mapping for timezones. Default is the mapping:
Abbreviation Interpretation UTC AMT America/Manaus UTC-4 AST America/Curacao UTC-4 CDT America/Costa_Rica UTC-5 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 - See also
YMD.parse
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.
Module Calendar.Austrian
- Description
Same as the
ISOcalendar, but with austrian as the default language.This calendar exist only for backwards compatible purposes.
Module Calendar.Badi
- Description
This is the Badi calendar, used in the Baha'i religion.
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
Gregoriancalendar, which is odd.
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
Gregoriancalendar; 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.
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.
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.
- 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
ISOcalendar - theGregoriancalendar has 1=Sunday, 7=Saturday.
Class Calendar.Event.Day_Event
- Description
Day_Eventis an abstract class, extendingEventfor events that are single days, using julian day numbers for the calculations.
- ConstantNODAY
constantintCalendar.Event.Day_Event.NODAY- Description
Returned from
scan_jdif the even searched for did not exist.
- Constantis_day_event
constantintCalendar.Event.Day_Event.is_day_event- Description
This constant may be used to identify
Day_Eventobjects.
- 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 1Forward (next),
-1Backward (previous).
- Returns
It should return the next or previous julian day (>jd) when the event occurs, or the constant
NODAYif it doesn't.
Class Calendar.Event.Easter
- Description
This class represents an easter.
- Methodcreate
Calendar.Event.EasterCalendar.Event.Easter(void|intshift)- Description
shiftis the year to shift from old to new style easter calculation. Default is 1582.
Class Calendar.Event.Easter_Relative
- Description
This class represents an easter relative event.
Class Calendar.Event.Event
- Description
Event is an abstract class, defining what methods an Event need to have.
- Constantis_event
constantintCalendar.Event.Event.is_event- Description
This constant may be used to identify an event object.
- Method`|
Method``| SuperEventres =Calendar.Event.Event()|withSuperEventres =with|Calendar.Event.Event()- Description
Joins several events into one
SuperEvent.
- 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.
scanusesnext, if not overloaded.- Example
Calendar.Event.Easter()->scan(Calendar.Year(2000)) => ({ Day(Sun 23 Apr 2000) })
- Note
scancan return an array of overlapping timeranges.This method must use in->calendar_object->type to create the returned timeranges, and must keep the ruleset.
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
- Constantis_fixed
constantintCalendar.Event.Gregorian_Fixed.is_fixed- Description
This constant may be used to identify
Gregorian_Fixedobjects.
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
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.
- 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
ISOcalendar - theGregoriancalendar 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
Class Calendar.Event.Nameday
- Description
This is created by the
Namedaysclasses to represent an event for a name.
Class Calendar.Event.Namedays
- Description
This contains a ruleset about namedays.
- Constantis_namedays
constantintCalendar.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.
Class Calendar.Event.NullEvent
- Description
A non-event.
Class Calendar.Event.Orthodox_Easter_Relative
- Description
This class represents an orthodox easter relative event.
Class Calendar.Event.Solar
- Description
This class represents a solar event as observed from Earth.
The
event_typeis one of0Northern hemisphere spring equinox.
1Northern hemisphere summer solstice.
2Northern hemisphere autumn equinox.
3Northern hemisphere winter solstice.
- Constantperiodic_table
protectedconstantperiodic_table- Description
Array array(float)0..Array float0Amplitude in days.
float1Cosine phase in radians in year 2000.
float2Period in radians/year.
- 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!
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
holidayset al first.
- 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
Namedaysobjects. Presumes non-overlapping namedays
- Variablenamedayss
Variableid array(Nameday) Calendar.Event.SuperNamedays.namedayssstringCalendar.Event.SuperNamedays.id
Class Calendar.Event.TZShift_Event
- Description
Event containing information about when a timezone is changed.
- 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)
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.saturdayandEvents.sunday.
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)
Module Calendar.Gregorian
- Description
This is the standard conservative christian calendar, used regularly in some countries - USA, for instance - and which derivate - the
ISOcalendar - is used in most of Europe.
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.
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
ISOfor 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.
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.
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.
- Methodtz_jd
arraytz_jd(intjulian_day)- 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.
Class Calendar.Stardate.cTick
- 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.
- Methodcreate
Module Calendar.Swedish
- Description
Same as the
ISOcalendar, but with Swedish as the default language.This calendar exist only for backwards compatible purposes.
Module Calendar.TZnames
- Description
This module contains listnings of available timezones, in some different ways
- Constantabbr2zones
constantCalendar.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.parsefunctions can handle timezone abbreviations by guessing.
- Constantzones
constantCalendar.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.
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 (
ISObyYMD, for instance).
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.
- 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.
- Methodset_ruleset
Methodruleset Calendarset_ruleset(Rulesetr)Rulesetruleset()- Description
Set or read the ruleset for the calendar.
set_rulesetreturns a new calendar object, but with the new ruleset.
- Methodset_timezone
Methodtimezone Calendarset_timezone(Timezonetz)Calendarset_timezone(string|Timezonetz)TimeZonetimezone()- Description
Set or get the current timezone (including dst) rule.
set_timezonereturns 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.SuperTimeRange
- Methodsecond
Methodseconds
Methodnumber_of_seconds
Methodminute
Methodminutes
Methodnumber_of_minutes
Methodhour
Methodhours
Methodnumber_of_hours Secondsecond()Secondsecond(intn)array(Second) seconds()array(Second) seconds(intfirst,intlast)intnumber_of_seconds()Minuteminute()Minuteminute(intn)array(Minute) minutes()array(Minute) minutes(intfirst,intlast)intnumber_of_minutes()Hourhour()Hourhour(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 aSuperTimeRangeis 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.
- Methodsecond
Class Calendar.Time.TimeofDay
- Description
Virtual class used by e.g. Hour.
- 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 Hourhour()Hourhour(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 tohour().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 Minuteminute()Minuteminute(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 tominute().number_of_minutes() simple counts the number of minutes containing the called time period.
- Methodmove_seconds
Methodmove_ns TimeRangemove_seconds(intseconds)TimeRangemove_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 Secondsecond()Secondsecond(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 tosecond().number_of_seconds() simple counts the number of seconds containing the called time period.
- Methodset_size_seconds
Methodset_size_ns TimeRangeset_size_seconds(intseconds)TimeRangeset_size_ns(intnanoseconds)- Description
These two methods allows the time range to be edited by size of specific units.
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 boolres =Calendar.TimeRanges.TimeRange()==compared_toboolequal(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
equalsmethod.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`&
TimeRangeres =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`*
TimeRangeres =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`- TimeRangeres =Calendar.TimeRanges.TimeRange()+nTimeRangeres =Calendar.TimeRanges.TimeRange()+offsetTimeRangeres =Calendar.TimeRanges.TimeRange()-mTimeRangeres =Calendar.TimeRanges.TimeRange()-x- Description
This calculates the (promoted) time period either n step away or with a given offset. These functions does use
addto 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()/narray(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 intres =Calendar.TimeRanges.TimeRange()/withinthow_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`> boolres =Calendar.TimeRanges.TimeRange()<compared_toboolres =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`^
TimeRangeres =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`|
TimeRangeres =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
TimeRangeadd(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 TimeRangebeginning()TimeRangeend()- Description
This gives back the zero-sized beginning or end of the called time period.
rule: range(t->beginning(),t->end())==t
- Methodcalendar
Calendarcalendar()- 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
`&
- 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_languageorset_rulesetto 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 TimeRangerange(TimeRangeother)TimeRangespace(TimeRangeother)TimeRangedistance(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 TimeRangeset_language(Rule.Languagelang)TimeRangeset_language(stringlang)Languagelanguage()- Description
Set or get the current language rule.
- Methodnext
Methodprev TimeRangenext()TimeRangeprev()- 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
TimeRangeplace(TimeRangethis)TimeRangeplace(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 TimeRangeset_ruleset(Rulesetr)TimeRangeruleset(Rulesetr)- Description
Set or get the current ruleset.
- Note
this may include timezone shanges, and change the time of day.
- Methodset_size
TimeRangeset_size(TimeRangesize)TimeRangeset_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 TimeRangeset_timezone(Timezonetz)TimeRangeset_timezone(stringtz)TimeZonetimezone()- 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)->...
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;itindexes 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_timezonetoo 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
constantCalendar.Timezone.locale=Rule.Timezone- Description
This contains the local timezone, found from various parts of the system, if possible.
- Constantlocaltime
constantCalendar.Timezone.localtime=Rule.Timezone- Description
This is a special timezone, that uses
localtime() andtznameto find out what current offset and timezone string to use.localeuses this if there is no other way of finding a better timezone to use.This timezone is limited by
localtimeand 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
- 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 callingSecond()->datetime().
- Methoddatetime_name
Methoddatetime_short_name stringdatetime_name(int|voidunix_time)stringdatetime_short_name(int|voidunix_time)- Description
Compat functions; same as
format_isoandformat_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
Daydwim_day(stringdate)Daydwim_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
Daydwim_time(stringdate_time)Daydwim_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
TimeRangeparse(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
- 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.
- Methodcreate
Class Calendar.YMD.Fraction
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.
- 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.
Class Calendar.YMD.YMD
- Description
Base (virtual) time period of the Roman-kind of calendar.
- 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
Dayday()Dayday(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 Secondsecond()Secondsecond(intn)Minuteminute(inthour,intminute,intsecond)array(Second) seconds()array(Second) seconds(intfirst,intlast)intnumber_of_seconds()Minuteminute()Minuteminute(intn)Minuteminute(inthour,intminute)array(Minute) minutes()array(Minute) minutes(intfirst,intlast)intnumber_of_minutes()Hourhour()Hourhour(intn)array(Hour) hours()array(Hour) hours(intfirst,intlast)intnumber_of_hours()
Class Calendar.YMD.Year
- Description
This is the time period of a year.
- 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
Monthmonth()Monthmonth(intn)Monthmonth(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
Weekweek()Weekweek(intn)Weekweek(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'.