Branch: Tag:

2001-05-05

2001-05-05 15:18:49 by Mirar (Pontus Hagland) <pike@sort.mirar.org>

removing "AutoDOC mk II" conversion
YMD.pmod: adding : to day/time separator in dwim

Rev: lib/modules/Calendar.pmod/Calendar.pike:1.5
Rev: lib/modules/Calendar.pmod/Coptic.pmod:1.5
Rev: lib/modules/Calendar.pmod/Discordian.pmod:1.6
Rev: lib/modules/Calendar.pmod/Event.pmod:1.13
Rev: lib/modules/Calendar.pmod/Gregorian.pmod:1.6
Rev: lib/modules/Calendar.pmod/ISO.pmod:1.6
Rev: lib/modules/Calendar.pmod/Islamic.pmod:1.6
Rev: lib/modules/Calendar.pmod/Julian.pmod:1.7
Rev: lib/modules/Calendar.pmod/Language.pmod:1.16
Rev: lib/modules/Calendar.pmod/Roman.pmod:1.5
Rev: lib/modules/Calendar.pmod/Ruleset.pike:1.9
Rev: lib/modules/Calendar.pmod/Stardate.pmod:1.7
Rev: lib/modules/Calendar.pmod/Swedish.pmod:1.6
Rev: lib/modules/Calendar.pmod/TZnames.pmod:1.9
Rev: lib/modules/Calendar.pmod/Time.pmod:1.13
Rev: lib/modules/Calendar.pmod/TimeRanges.pmod:1.17
Rev: lib/modules/Calendar.pmod/Timezone.pmod:1.18
Rev: lib/modules/Calendar.pmod/YMD.pmod:1.31

1: - // $Id: TimeRanges.pmod,v 1.16 2001/04/27 16:56:59 grubba Exp $ + //! module Calendar    -  + // $Id: TimeRanges.pmod,v 1.17 2001/05/05 15:18:49 mirar Exp $ +    #pike __REAL_VERSION__      #define zero int(0..0)
17:   Ruleset default_rules=    master()->resolv("Calendar")["default_rules"];    + //------------------------------------------------------------------------ + //! class TimeRange   //! This is the base class for any time measurement   //! and calendrar information. It defines all the   //! things you can do with a time range, any time
29:   //! and thereby reducing it to just 7 days),   //! no matter when in time the actual day were.   //! + //------------------------------------------------------------------------ +    class TimeRange   {    constant is_timerange=1;       Ruleset rules;    -  //! @decl void create("unix", int unixtime) -  //! @decl void create("unix", int unixtime, int seconds_len) + //! method void create("unix",int unixtime) + //! method void create("unix",int unixtime,int seconds_len)   //! Create the timerange from unix time (as given by -  //! @tt{time(2)@}), with eventually the size of + //! <tt>time(2)</tt>), with eventually the size of   //! the time range in the same unit, seconds. -  -  //! @decl void create("julian", int|float julian_day) + //! + //! method void create("julian",int|float julian_day)   //! 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. -  -  //! @decl void create(TimeRange from) + //! + //! method void create(TimeRange from)   //! 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()] + //! or languges - use <ref>set_timezone</ref>, + //! <ref>set_language</ref> or <ref>set_ruleset</ref>   //! to achieve this.   //! -  //! @note + //! note:    //! The size of the new object may be inexact;    //! a Month object can't comprehend seconds, for instance.   
140:    object_program(this_object()));    }    -  //! @decl TimeRange set_size(TimeRange size) -  //! @decl TimeRange set_size(int n, TimeRange size) + //! method TimeRange set_size(TimeRange size) + //! method TimeRange set_size(int n,TimeRange size)   //! 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 + //! If <i>n</i> are given, the resulting size + //! will be <i>n</i> amounts of the given size. + //! note:    //! A negative size is not permitted; a zero one are.      // virtual
171:    return _set_size(n,[object(TimeRange)]x);    }    -  //!@decl TimeRange add(int n, void|TimeRange step) -  //! Calculates the (promoted) time period n steps away; -  //! if @[step] is not specified, the step's length is of the + //! method TimeRange add(int n,void|TimeRange step) + //! 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
182:    //! period. (Like week 53, day 31 of a month or the leap day of a year.)    //!    //! Recommended use are like this: -  //! @code{ + //! <pre>   //! // 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++) + //! for (int i=0; i&lt;10; i++)   //! {   //! month++;   //! TimeRange day=month->place(orig_day); -  //! @i{...use day...@} + //! <i>...use day...</i>   //! } -  //! @} + //! </pre>      // virtual    static this_program _add(int n,this_program step);
214:    return _add(n,[object(this_program)]x);    }    -  //! @decl TimeRange place(TimeRange this) -  //! @decl TimeRange place(TimeRange this, int(0..1) force) + //! method TimeRange place(TimeRange this) + //! method TimeRange place(TimeRange this,int(0..1) force)   //! This will place the given timerange in this timerange,   //! for instance, day 37 in the year - -  //! @tt{Year(1934)->place(Day(1948 d37)) => Day(1934 d37)@}. + //! <tt>Year(1934)->place(Day(1948 d37)) => Day(1934 d37)</tt>.   //! -  //! @note + //! note:   //! The rules how to place things in different timeranges   //! can be somewhat 'dwim'.      // virtual    TimeRange place(TimeRange what,void|int force);    -  //! @decl TimeRange `+(int n) -  //! @decl TimeRange `+(TimeRange offset) -  //! @decl TimeRange `-(int m) -  //! @decl TimeRange `-(TimeRange x) -  //! These calculate the (promoted) time period -  //! either @[n] steps away or at a given @[offset]. -  //! -  //! These functions use @[add()] to really -  //! perform the work: -  //! @pre{ + //! method TimeRange `+(int n) + //! method TimeRange `+(TimeRange offset) + //! method TimeRange `-(int m) + //! method TimeRange `-(TimeRange x) + //! This calculates the (promoted) time period + //! either n step away or with a given offset. + //! These functions does use <ref>add</ref> to really + //! do the job: + //! <pre>    //! 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
245:    //! n-t illegal    //! offset+t offset->add(1,t) | note this!    //! offset-t offset->add(-1,t) | -  //! @} + //! </pre>   //!   //! Mathematic rules: -  //! @pre{ + //! <pre>   //! 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 -  //! @} + //! </pre>   //! -  //! @note + //! note:   //! a-b does not give the distance between the start of a and b. -  //! Use the @[distance()] function to calculate that. + //! Use the <ref>distance</ref>() function to calculate that.   //! -  //! The integer used to @[`+()], @[`-()] and @[add()] are the @i{number@} -  //! of steps the motion will be. It does @i{never@} represent -  //! any @i{fixed@} amount of time, like seconds or days. + //! The integer used to `+, `- and add are the <i>number</i> + //! of steps the motion will be. It does <i>never</i> represent + //! any <i>fixed</i> amount of time, like seconds or days.       TimeRange `+(program|this_program|int n)    {
282:    return add(-n);    }    -  //! @decl TimeRange next() -  //! @decl TimeRange prev() -  //! These are compatibility and convinience functions; -  //! @code{a->next()@} is exactly the same as @code{a + 1@}; -  //! @code{a=a->next()@} is the same as @code{a++@}. + //! method TimeRange next() + //! method TimeRange prev() + //! Next and prev are compatible and convinience functions; + //! <tt>a->next()</tt> is exactly the same as <tt>a+1</tt>; + //! <tt>a=a->next()</tt> is <tt>a++</tt>.       TimeRange next()    {
298:    return this_object()-1;    }    -  //! @decl TimeRange `*(int n) + //! method TimeRange `*(int n)   //! This changes the amount of time in -  //! the time period. @code{t * 17@} is -  //! the same as doing @code{t->@[set_size](t, 17)@}. + //! the time period. <tt>t*17</tt> is + //! the same as doing <tt>t-><ref>set_size</ref>(t,17)</tt>.       function ``* = `*;    TimeRange `*(int n)
309:    return set_size(n,this_object());    }    -  //! @decl array(TimeRange) `/(int n) -  //! @decl array(TimeRange) split(int n) + //! method array(TimeRange) `/(int n) + //! method array(TimeRange) split(int n)   //! This divides the called timerange into -  //! @[n] pieces. The returned timerange type + //! n pieces. The returned timerange type   //! is not neccesarily of the same type as the called one.   //! -  //! @bugs + //! known bugs:   //! These are currently not defined for -  //! @[SuperTimeRange]. + //! <ref to=SuperTimeRange>supertimeranges</ref>.    -  //! @decl int `/(TimeRange with) -  //! @decl int how_many(TimeRange with) + //! method int `/(TimeRange with) + //! method int how_many(TimeRange with)   //! 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 @[YMD.Year]. + //! with the instance of a <ref to=YMD.Year>Year</ref>.      // virtual    array(TimeRange) split(int n);
400:    else return how_many(x);    }    -  //! @decl int offset_to(TimeRange x) + //! method int offset_to(TimeRange x)   //! 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: -  //! @code{a+a->@[offset_to](b)==b@} + //! <tt>a+a->offset_to(b)==b</tt>    //!    //! By suitable means that a and b are of the same    //! type and size. This is obviously true only
420:    return this_object()->distance(x)/this_object();    }    -  //! @decl TimeRange beginning() -  //! @decl TimeRange end() + //! method TimeRange beginning() + //! method TimeRange end()   //! This gives back the zero-sized beginning   //! or end of the called time period.   //!   //! rule: -  //! @code{range(t->beginning(),t->end()) == t@} + //! <tt>range(t->beginning(),t->end())==t</tt>       TimeRange beginning();    TimeRange end();    -  //! @decl TimeRange range(TimeRange other) -  //! @decl TimeRange space(TimeRange other) -  //! @decl TimeRange distance(TimeRange other) + //! method TimeRange range(TimeRange other) + //! method TimeRange space(TimeRange other) + //! method TimeRange distance(TimeRange other)   //! Derives different time periods in between   //! the called timerange and the parameter timerange.   //! -  //! @pre{ -  //! <- the past the future -> -  //! |--called--| |--other--| -  //! >------------ range -----------< -  //! >--space--< -  //! >----- distance -----< -  //! @} + //! <pre> + //! &gt;- the past the future -&lt; + //! |--called--| |--other--| + //! &gt;------------ range -----------&lt; + //! &gt;--space--&lt; + //! &gt;----- distance -----&lt; + //! </pre>   //! -  //! @seealso -  //! @[add()], @[TimeRanges->range()], @[TimeRanges->space()], -  //! @[TimeRanges->distance()] + //! See also: add, TimeRanges.range, TimeRanges.space, TimeRanges.distance      // virtual    TimeRange distance(TimeRange to);
463:    }       -  //! @decl int(0..1) strictly_preceeds(TimeRange what); -  //! @decl int(0..1) preceeds(TimeRange what); -  //! @decl int(0..1) is_previous_to(TimeRange what); -  //! @decl int(0..1) overlaps(TimeRange what); -  //! @decl int(0..1) contains(TimeRange what); -  //! @decl int(0..1) equals(TimeRange what); -  //! @decl int(0..1) is_next_to(TimeRange what); -  //! @decl int(0..1) succeeds(TimeRange what); -  //! @decl int(0..1) strictly_succeeds(TimeRange what); + //! method int(0..1) strictly_preceeds(TimeRange what); + //! method int(0..1) preceeds(TimeRange what); + //! method int(0..1) is_previous_to(TimeRange what); + //! method int(0..1) overlaps(TimeRange what); + //! method int(0..1) contains(TimeRange what); + //! method int(0..1) equals(TimeRange what); + //! method int(0..1) is_next_to(TimeRange what); + //! method int(0..1) succeeds(TimeRange what); + //! method int(0..1) strictly_succeeds(TimeRange what);   //! These methods exists to compare two periods   //! of time on the timeline.   //! -  //! @pre{ + //! <pre>   //! case predicates   //! -  //! <-- past future -> + //! &lt;-- past future -&gt;    //!    //! |----A----| A strictly preceeds B,    //! |----B----| A preceeds B
510:    //! |----A----| A strictly succeeds B,    //! |----B----| A succeeds B    //! -  //! @} + //! </pre>   //! -  //! @note + //! note:   //! These methods only check the range of the first to the   //! last time in the period;   //! use of combined time periods (<ref>SuperTimeRange</ref>s)   //! might not give you the result you want.   //! -  //! @seealso -  //! @[`&()] + //! see also: `&    -  +    //- internal method   //- returns [-1,0,1] for comparison between   //- (in order) begin/begin,begin/end,end/begin and end/end
635:    return !a[END_END];    }    -  //! @decl int(0..1) `<(TimeRange compared_to) -  //! @decl int(0..1) `>(TimeRange compared_to) -  //! These operators roughly sort on the + //! method int(0..1) `<(TimeRange compared_to) + //! method int(0..1) `>(TimeRange compared_to) + //! 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.
660:    return 0;    }    -  //! @decl int(0..1) `==(TimeRange compared_to) -  //! @decl int(0..1) _equal(TimeRange compared_to) -  //! These two overload the operator @[predef::`==()] and -  //! the result of the @[predef::equal()] function. + //! method int(0..1) `==(TimeRange compared_to) + //! method int(0..1) _equal(TimeRange compared_to) + //! These two overloads the operator <tt>`==</tt> and + //! the result of the <tt>equal</tt> function.   //! -  //! a @tt{==@} b is considered true if the two + //! a<tt>==</tt>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.   //! -  //! @code{@[equal](a, b)@} is considered + //! <tt>equal(</tt>a<tt>,</tt>b<tt>)</tt> are considered   //! true if a and b are the same timerange, exactly the same -  //! as the @[equals()] method. + //! as the <ref>equals</ref> method.   //! -  //! The @[__hash()] method is also present, + //! The <tt>__hash</tt> method is also present,   //! to make timeranges possible to use as keys in mappings.   //! -  //! @bugs -  //! @[_equal()] is currently not possible to overload, -  //! due to wierd bugs, so @[predef::equal()] uses @[`==()] for now. + //! known bugs: + //! _equal is not currently possible to overload, + //! due to wierd bugs, so equal uses `== for now.       int(0..1) `==(TimeRange what)    {
694:   // return equals(what);   // }    -  //! @decl TimeRange `&(TimeRange with) + //! method TimeRange `&(TimeRange with)   //! Gives the cut on the called time period   //! with another time period. The result is   //! zero if the two periods doesn't overlap. -  //! @pre{ -  //! <- the past the future -> -  //! |-------called-------| -  //! |-------other--------| -  //! >----- cut -----< -  //! @} + //! <pre> + //! &gt;- the past the future -&lt; + //! |-------called-------| + //! |-------other--------| + //! &gt;----- cut -----&lt; + //! </pre>       function ``& = `&;    TimeRange|zero `&(TimeRange with, mixed ...extra)
731:    return res;    }    -  //! @decl TimeRange `|(TimeRange with) + //! method TimeRange `|(TimeRange with)   //! Gives the union on the called time period   //! and another time period. -  //! @pre{ -  //! >- the past the future -< -  //! |-------called-------| -  //! |-------other--------| -  //! <----------union----------> -  //! @} + //! <pre> + //! &gt;- the past the future -&lt; + //! |-------called-------| + //! |-------other--------| + //! &lt;----------union----------&gt; + //! </pre>       function ``| = `|;    TimeRange `|(TimeRange with,mixed ...extra)
768:    return from;    }    -  //! @decl TimeRange `^(TimeRange with) + //! method TimeRange `^(TimeRange with)   //! 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. -  //! @pre{ -  //! >- the past the future -< -  //! |-------called-------| -  //! |-------other--------| -  //! <----| |----> - exclusive or -  //! @} + //! <pre> + //! &gt;- the past the future -&lt; + //! |-------called-------| + //! |-------other--------| + //! &lt;----| |----> - exclusive or + //! </pre>       function ``^ = `^;    TimeRange `^(TimeRange with,mixed ... extra)
824:    return res;    }    -  //! @decl TimeRange subtract(TimeRange what) + //! method TimeRange subtract(TimeRange what)   //! This subtracts a period of time from another; -  //! @pre{ -  //! >- the past the future -< + //! <pre> + //! &gt;- the past the future -&lt;   //! |-------called-------|   //! |-------other--------| -  //! <----> <- called->subtract(other) + //! &lt;----&gt; &lt;- called-&gt;subtract(other)   //!   //! |-------called-------|   //! |---third---| -  //! <----> <---> <- called->subtract(third) -  //! @} + //! &lt;----&gt; &lt;---> &lt;- called->subtract(third) + //! </pre>       TimeRange subtract(TimeRange what,mixed ... extra)    {
879:    return res;    }    -  //! @decl TimeRange set_ruleset(Ruleset r) -  //! @decl TimeRange ruleset(Ruleset r) + //! method TimeRange set_ruleset(Ruleset r) + //! method TimeRange ruleset(Ruleset r)   //! Set or get the current ruleset. -  //! @note + //! note:    //! this may include timezone shanges,    //! and change the time of day.   
892:    return rules;    }    -  //! @decl TimeRange set_timezone(Timezone tz) -  //! @decl TimeRange set_timezone(string tz) -  //! @decl TimeZone timezone() + //! method TimeRange set_timezone(Timezone tz) + //! method TimeRange set_timezone(string tz) + //! method TimeZone timezone()   //! Set or get the current timezone (including dst) rule.   //! -  //! @note + //! 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:   //! -  //! @tt{Year(2003)->...->set_timezone(TimeZone.CET)->...->hour(14)->...@} + //! <tt>Year(2003)-&gt;...-&gt;set_timezone(TimeZone.CET)-&gt;...-&gt;hour(14)-&gt;...</tt>    //!       TimeRange set_timezone(string|Ruleset.Timezone tz)
917:    return rules->timezone;    }    -  //! @decl TimeRange set_language(Language lang) -  //! @decl TimeRange set_language(string lang) -  //! @decl Language language() + //! method TimeRange set_language(Language lang) + //! method TimeRange set_language(string lang) + //! method Language language()    //! Set or get the current language rule.       TimeRange set_language(string|Ruleset.Language lang)
932:    return rules->language;    }    -  //! @decl Calendar calendar() + //! method Calendar calendar()    //! Simply gives back the calendar in use, for instance    //! Calendar.ISO or Calendar.Discordian.   
944:      // ----------------------------------------------------------------    + //! + //! module Calendar   //! class SuperTimeRange   //! This class handles the cases where you have a time   //! period with holes. These can be created by the   //! <tt>^</tt> or <tt>|</tt> operators on time ranges. -  + //! inherits TimeRange +    class cSuperTimeRange   { -  //! inherits TimeRange +     inherit TimeRange;       constant is_supertimerange=1;       array parts;    -  //! @decl void create(array(TimeRange) parts) + //! method void create(array(TimeRange) parts)    //! A SuperTimeRange must have at least two parts,    //! two time ranges. Otherwise, it's either not    //! a time period at all or a normal time period.
1137:    }   }    - //! @decl TimeRange nulltimerange + //! constant TimeRange nulltimerange   //! 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 + //! <ref>`&</ref> 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. + //! It has a constant, <tt>is_nulltimerange</tt>, which + //! is non-zero. <tt>`!</tt> on this timerange is true.         program NullTimeRange=cNullTimeRange;