Function: icalendar-date-time-variant

icalendar-date-time-variant is a byte-compiled function defined in icalendar-utils.el.gz.

Signature

(icalendar-date-time-variant DT &key SECOND MINUTE HOUR DAY MONTH YEAR (DST -1 GIVEN-DST) (ZONE nil GIVEN-ZONE) TZ)

Documentation

Return a variant of DT with slots modified as in the given arguments.

DT should be an icalendar-date-time; the keyword arguments have the same meanings as in make-decoded-time. The returned variant will have slot values as specified by the arguments or copied from DT, except that the weekday slot will be updated if necessary, and the zone and dst fields will not be set unless given explicitly (because varying the date and clock time generally invalidates the time zone information in DT).

One additional keyword argument is accepted: :tz. If provided, its value should be an icalendar-vtimezone, an icalendar-utc-offset, or the symbol 'preserve. If it is a time zone component, the zone and dst slots in the returned variant will be adjusted to the correct values in the given time zone for the local time represented by the variant. If it is a UTC offset, the variant's zone slot will contain this value, but its dst slot will not be adjusted. If it is the symbol
'preserve, then both the zone and dst fields are copied from DT into
the variant.

Source Code

;; Defined in /usr/src/emacs/lisp/calendar/icalendar-utils.el.gz
(cl-defun ical:date-time-variant (dt &key second minute hour
                                          day month year
                                          (dst -1 given-dst)
                                          (zone nil given-zone)
                                          tz)
  "Return a variant of DT with slots modified as in the given arguments.

DT should be an `icalendar-date-time'; the keyword arguments have the
same meanings as in `make-decoded-time'.  The returned variant will have
slot values as specified by the arguments or copied from DT, except that
the weekday slot will be updated if necessary, and the zone and dst
fields will not be set unless given explicitly (because varying the date
and clock time generally invalidates the time zone information in DT).

One additional keyword argument is accepted: `:tz'.  If provided, its
value should be an `icalendar-vtimezone', an `icalendar-utc-offset', or
the symbol \\='preserve.  If it is a time zone component, the zone and
dst slots in the returned variant will be adjusted to the correct
values in the given time zone for the local time represented by the
variant.  If it is a UTC offset, the variant's zone slot will contain
this value, but its dst slot will not be adjusted.  If it is the symbol
\\='preserve, then both the zone and dst fields are copied from DT into
the variant."
  (require 'icalendar-recur) ; for icr:tz-set-zone; avoids circular requires
  (declare-function icalendar-recur-tz-set-zone "icalendar-recur")

  (let ((variant
         (make-decoded-time :second (or second (decoded-time-second dt))
                            :minute (or minute (decoded-time-minute dt))
                            :hour (or hour (decoded-time-hour dt))
                            :day (or day (decoded-time-day dt))
                            :month (or month (decoded-time-month dt))
                            :year (or year (decoded-time-year dt))
                            ;; For zone and dst slots, trust the value
                            ;; if explicitly specified or explicitly
                            ;; requested to preserve, but not otherwise
                            :dst (cond (given-dst dst)
                                       ((eq 'preserve tz) (decoded-time-dst dt))
                                       (t -1))
                            :zone (cond (given-zone zone)
                                        ((eq 'preserve tz) (decoded-time-zone dt))
                                        (t nil)))))
    ;; update weekday slot when possible, since it depends on the date
    ;; slots, which might have changed.  (It's not always possible,
    ;; because pure time values are also represented as decoded-times,
    ;; with empty date slots.)
    (unless (or (null (decoded-time-year variant))
                (null (decoded-time-month variant))
                (null (decoded-time-day variant)))
      (setf (decoded-time-weekday variant)
            (calendar-day-of-week (ical:date-time-to-date variant))))
    ;; if given a time zone or UTC offset, update zone and dst slots,
    ;; which also might have changed:
    (when (and tz (not (eq 'preserve tz)))
      (icalendar-recur-tz-set-zone variant tz))
    variant))