21. Calendar

Return a year in the vahid by number or name:

vahid->year("Alif")

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

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

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.

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

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.

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

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

This constant may be used to identify Day_Event objects.

Uses the virtual method scan_jd.

Event.next

Uses the virtual method scan_jd.

Event.previous

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

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

This class represents an easter.

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

Calculates the year day for the easter.

This class represents an easter relative event.

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

This constant may be used to identify an event object.

Joins several events into one SuperEvent.

Returns a description of the event.

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.

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

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.

Returns a mapping with time ranges mapped to events.

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

Julian_Fixed

This constant may be used to identify Gregorian_Fixed objects.

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

Gregorian_Fixed

This constant may be used to identify Julian_Fixed objects.

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.

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

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.

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

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

This constant may be used to identify Nameday objects.

This contains a ruleset about namedays.

This constant may be used to identify Namedays.

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.

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

A non-event.

This constant may be used to identify a NullEvent.

This class represents an orthodox easter relative event.

This class represents a solar event as observed from Earth.

The event_type is one of

Uses the virtual method scan_jd.

Event.previous

Returns unixtime in UTC to avoid losing the decimals!

Calculate the next event.

Based on Meeus Astronomical Algorithms Chapter 27.

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

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

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

Container for merged Namedays objects. Presumes non-overlapping namedays

Event containing information about when a timezone is changed.

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.

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

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.

Contains a time zone.

Offset to UTC, not counting DST.

The name of the time zone.

Returns the offset to UTC, not counting DST.

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.

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)

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

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

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

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

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

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.

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.

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.

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

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

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)

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.

Virtual class used by e.g. Hour.

Creates a call_out to this point in time.

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

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

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]

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

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

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.

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.

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.

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.

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.

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

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.

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.

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.

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

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

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

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.

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.

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.

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.

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
 

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

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

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

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

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

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

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
 
 

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.

`&

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.

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

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.

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

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

Set or get the current language rule.

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

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.

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

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

Set or get the current ruleset.

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

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.

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

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

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

This subtracts a period of time from another;

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

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.

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.

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.

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

the weekday-from-string routine is language dependent.

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

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

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.

Get day number n in the current range.

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

Get the days in the current range.

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"

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

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

Get the number of days in the current range.

This is the time period of a year.

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.

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

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