Function: encode-time

encode-time is a function defined in timefns.c.

Signature

(encode-time TIME &rest OBSOLESCENT-ARGUMENTS)

Documentation

Convert TIME to a timestamp.

TIME is a list (SECOND MINUTE HOUR DAY MONTH YEAR IGNORED DST ZONE) in the style of decode-time, so that (encode-time (decode-time ...)) works. In this list, ZONE can be nil for Emacs local time, t for Universal Time, wall for system wall clock time, or a string as in the TZ environment variable. ZONE can also be a list (as from current-time-zone) or an integer (as from decode-time) applied without consideration for daylight saving time. If ZONE specifies a time zone with daylight-saving transitions, DST is t for daylight saving time, nil for standard time, and -1 to cause the daylight saving flag to be guessed.

TIME can also be a list (SECOND MINUTE HOUR DAY MONTH YEAR), which is equivalent to (SECOND MINUTE HOUR DAY MONTH YEAR nil -1 nil).

As an obsolescent calling convention, if this function is called with
6 or more arguments, the first 6 arguments are SECOND, MINUTE, HOUR,
DAY, MONTH, and YEAR, and specify the components of a decoded time. If there are more than 6 arguments the *last* argument is used as ZONE and any other extra arguments are ignored, so that (apply
#'encode-time (decode-time ...)) works. In this obsolescent
convention, DST is -1 and ZONE defaults to nil.

The range of supported years is at least 1970 to the near future. Out-of-range values for SECOND through MONTH are brought into range via date arithmetic. This can be tricky especially when combined with DST; see Info node (elisp)Time Conversion for details and caveats.

View in manual

Probably introduced at or before Emacs version 19.29.

Source Code

// Defined in /usr/src/emacs/src/timefns.c
{
  struct tm tm;
  Lisp_Object zone = Qnil;
  Lisp_Object a = args[0];
  Lisp_Object secarg, minarg, hourarg, mdayarg, monarg, yeararg;
  tm.tm_isdst = -1;

  if (nargs == 1)
    {
      Lisp_Object tail = a;
      for (int i = 0; i < 6; i++, tail = XCDR (tail))
	CHECK_CONS (tail);
      secarg = XCAR (a); a = XCDR (a);
      minarg = XCAR (a); a = XCDR (a);
      hourarg = XCAR (a); a = XCDR (a);
      mdayarg = XCAR (a); a = XCDR (a);
      monarg = XCAR (a); a = XCDR (a);
      yeararg = XCAR (a); a = XCDR (a);
      if (! NILP (a))
	{
	  CHECK_CONS (a);
	  a = XCDR (a);
	  CHECK_CONS (a);
	  Lisp_Object dstflag = XCAR (a); a = XCDR (a);
	  CHECK_CONS (a);
	  zone = XCAR (a);
	  if (SYMBOLP (dstflag) && !FIXNUMP (zone) && !CONSP (zone))
	    tm.tm_isdst = !NILP (dstflag);
	}
    }
  else if (nargs < 6)
    xsignal2 (Qwrong_number_of_arguments, Qencode_time, make_fixnum (nargs));
  else
    {
      if (6 < nargs)
	zone = args[nargs - 1];
      secarg = a;
      minarg = args[1];
      hourarg = args[2];
      mdayarg = args[3];
      monarg = args[4];
      yeararg = args[5];
    }

  /* Let SEC = floor (LT.ticks / HZ), with SUBSECTICKS the remainder.  */
  struct lisp_time lt;
  decode_lisp_time (secarg, false, &lt, 0);
  Lisp_Object hz = lt.hz, sec, subsecticks;
  if (FASTER_TIMEFNS && BASE_EQ (hz, make_fixnum (1)))
    {
      sec = lt.ticks;
      subsecticks = make_fixnum (0);
    }
  else
    {
      mpz_fdiv_qr (mpz[0], mpz[1],
		   *bignum_integer (&mpz[0], lt.ticks),
		   *bignum_integer (&mpz[1], hz));
      sec = make_integer_mpz ();
      mpz_swap (mpz[0], mpz[1]);
      subsecticks = make_integer_mpz ();
    }
  tm.tm_sec  = check_tm_member (sec, 0);
  tm.tm_min  = check_tm_member (minarg, 0);
  tm.tm_hour = check_tm_member (hourarg, 0);
  tm.tm_mday = check_tm_member (mdayarg, 0);
  tm.tm_mon  = check_tm_member (monarg, 1);
  tm.tm_year = check_tm_member (yeararg, TM_YEAR_BASE);

  timezone_t tz = tzlookup (zone, false);
  tm.tm_wday = -1;
  time_t value = mktime_z (tz, &tm);
  int mktime_errno = errno;
  xtzfree (tz);

  if (tm.tm_wday < 0)
    time_error (mktime_errno);

  if (BASE_EQ (hz, make_fixnum (1)))
    return (current_time_list
	    ? list2 (hi_time (value), lo_time (value))
	    : INT_TO_INTEGER (value));
  else
    {
      struct lisp_time val1 = { INT_TO_INTEGER (value), make_fixnum (1) };
      Lisp_Object secticks = lisp_time_hz_ticks (val1, hz);
      Lisp_Object ticks = lispint_arith (secticks, subsecticks, false);
      return Fcons (ticks, hz);
    }
}