Function: icalendar-recur-make-interval

icalendar-recur-make-interval is a byte-compiled function defined in icalendar-recur.el.gz.

Signature

(icalendar-recur-make-interval LOW HIGH &optional NEXT-LOW)

Source Code

;; Defined in /usr/src/emacs/lisp/calendar/icalendar-recur.el.gz
;; Recurrence Intervals
;;
;; Two important ideas in the following:
;;
;; 1) Because recurrence sets are potentially infinite, we always
;; calculate recurrences within certain upper and lower bounds.  These
;; bounds might be determined by a user interface (e.g. the week or
;; month displayed in a calendar) or might be derived from the logic of
;; the recurrence rule itself.  In the former case, where the bounds can
;; be arbitrary, it's called a 'window' here (as in "window of
;; time").  In the latter case, it's called an 'interval' here (after the
;; "INTERVAL=..." clause in recurrence rules).
;;
;; Unlike a window, an interval must be synced up with the recurrence
;; rule: its bounds must fall at successive integer multiples of the
;; product of the recurrence rule's FREQ and INTERVAL values, relative
;; to a starting date/time.  For example, a recurrence rule with a
;; MONTHLY frequency and INTERVAL=3 will have an interval that is three
;; months long.  If its start date is, e.g., in November, then the first
;; interval runs from November to February, the next from February to
;; May, and so on.  Because intervals depend only on the starting
;; date/time, the frequency, and the interval length, it is relatively
;; straightforward to compute the bounds of the interval surrounding an
;; arbitrary point in time (without enumerating them successively from
;; the start time); see `icalendar-recur-find-interval', which calls
;; this arbitrary point in time the 'target'.
;;
;; 2) An interval is the smallest unit of time for which we compute
;; values of the recurrence set.  This is because the "BYSETPOS=..."
;; clause in a recurrence rule operates on the sequence of recurrences
;; in a single interval.  Since it selects recurrences by their index in
;; this sequence, the sequence must have a determinate length and known
;; bounds.  The function `icalendar-recur-recurrences-in-interval' is the
;; main function to compute recurrences in a given interval.
;;
;; The way to compute the recurrences in an arbitrary *window* is thus
;; to find the interval bounds which are closest to the window's lower
;; and upper bound, and then compute the recurrences for all the
;; intervals in between, i.e., that "cover" the window.  This is what the
;; function `icalendar-recur-recurrences-in-window' does.
;;
;; Note that the recurrence set for a recurrence rule with a COUNT
;; clause cannot be computed for an arbitrary interval (or window);
;; instead, the set must be enumerated from the beginning, so that the
;; enumeration can stop after a fixed number of recurrences.  This is
;; what the function `icalendar-recur-recurrences-to-count' does.  But
;; also in this case, recurrences are generated for one interval at a
;; time, because a BYSETPOS clause might apply.
;;
;; An interval is represented as a vector like [LOW HIGH NEXT-LOW] of
;; decoded times.  The length of time between LOW and HIGH corresponds
;; to the FREQ rule part: they are one year apart for a 'YEARLY rule, a
;; month apart for a 'MONTHLY rule, etc.  NEXT-LOW is the upper bound of
;; the interval: it is equal to LOW in the subsequent interval.  When
;; the INTERVAL rule part is equal to 1 (the default), HIGH and NEXT-LOW
;; are the same, but if it is > 1, NEXT-LOW is equal to LOW + INTERVAL *
;; FREQ.  (For performance reasons, NEXT-LOW is therefore left out of
;; the vector when it is redundant.)  For example, in a 'MONTHLY rule
;; where INTERVAL=3, which means "every three months", LOW and HIGH
;; bound the first month, while HIGH and NEXT-LOW bound the following
;; two months.
;;
;; The times between LOW and HIGH are candidates for recurrences.  LOW
;; is an inclusive lower bound, and HIGH is an exclusive upper bound:
;; LOW <= R < HIGH for each recurrence R in the interval.  The times
;; between HIGH and NEXT-LOW are not candidates for recurrences.

(defun icr:make-interval (low high &optional next-low)
  (if next-low
      (vector low high next-low)
    (vector low high)))