Emacs Lisp Date Time Formats

Perm url with updates: http://xahlee.org/emacs/elisp_datetime.html

Emacs Lisp Date Time Formats

Xah Lee, 2010-11-29

A little emacs lisp tips on working with date time.

ISO 8601 Format

Elisp provides a very convenient function “format-time-string” for printing data time. For example, you can write a command to print date in the yyyy-mm-dd format using 「(insert (format-time-string "%Y-%m-%d"))」. Here's the full code:

(defun insert-date ()
  "Insert current date yyyy-mm-dd."
  (when (region-active-p)
    (delete-region (region-beginning) (region-end) )
  (insert (format-time-string "%Y-%m-%d"))

The “region-active-p” may be new in emacs 23. For emacs 22, use 「(and transient-mark-mode mark-active)」.

In many web tech spec (e.g. Atom Webfeed Format), a full ISO 8601 format is required, like this: 「2010-11-28T13:55Z」. You can code it like this:

(defun insert-date-time ()
  "Insert current date-time string in full
ISO 8601 format.
Example: 2010-11-29T23:23:35-08:00
See: URL `http://en.wikipedia.org/wiki/ISO_8601'
  (when (region-active-p)
    (delete-region (region-beginning) (region-end) )
    (format-time-string "%Y-%m-%dT%T")
    ((lambda (x) (concat (substring x 0 3) ":" (substring x 3 5)))
     (format-time-string "%z")))))

Ordinal Date

“format-time-string” also supports ordinal date format. For example, “2010 Jan 1st” is “2010-001”, and “2010 December 31” is “2010-365”. The code is this:

(format-time-string "%Y-%j") ; "2010-334" for 2010-11-30

Names for Month and Week

You can also print names for month and week, both full name or abbrevation.

(format-time-string "%B %b") ; "November Nov"
(format-time-string "%A %a") ; "Tuesday Tue"

Unix time format

To print Unix time format (i.e. number of seconds since 1970-01-01 00:00:00 +0000.), use 「%s」. Like this:

(format-time-string "%s") ; "1291104066"

Documentation of format-time-string

Call “describe-function” to see the inline doc of “format-time-string”. Here's the output:

format-time-string is a built-in function in `C source code'.

(format-time-string FORMAT-STRING &optional TIME UNIVERSAL)

Use FORMAT-STRING to format the time TIME, or now if omitted.
TIME is specified as (HIGH LOW . IGNORED), as returned by
`current-time' or `file-attributes'.  The obsolete form (HIGH . LOW)
is also still accepted.
The third, optional, argument UNIVERSAL, if non-nil, means describe TIME
as Universal Time; nil means describe TIME in the local time zone.
The value is a copy of FORMAT-STRING, but with certain constructs replaced
by text that describes the specified date and time in TIME:

%Y is the year, %y within the century, %C the century.
%G is the year corresponding to the ISO week, %g within the century.
%m is the numeric month.
%b and %h are the locale's abbreviated month name, %B the full name.
%d is the day of the month, zero-padded, %e is blank-padded.
%u is the numeric day of week from 1 (Monday) to 7, %w from 0 (Sunday) to 6.
%a is the locale's abbreviated name of the day of week, %A the full name.
%U is the week number starting on Sunday, %W starting on Monday,
 %V according to ISO 8601.
%j is the day of the year.

%H is the hour on a 24-hour clock, %I is on a 12-hour clock, %k is like %H
 only blank-padded, %l is like %I blank-padded.
%p is the locale's equivalent of either AM or PM.
%M is the minute.
%S is the second.
%Z is the time zone name, %z is the numeric form.
%s is the number of seconds since 1970-01-01 00:00:00 +0000.

%c is the locale's date and time format.
%x is the locale's "preferred" date format.
%D is like "%m/%d/%y".

%R is like "%H:%M", %T is like "%H:%M:%S", %r is like "%I:%M:%S %p".
%X is the locale's "preferred" time format.

Finally, %n is a newline, %t is a tab, %% is a literal %.

Certain flags and modifiers are available with some format controls.
The flags are `_', `-', `^' and `#'.  For certain characters X,
%_X is like %X, but padded with blanks; %-X is like %X,
but without padding.  %^X is like %X, but with all textual
characters up-cased; %#X is like %X, but with letter-case of
all textual characters reversed.
%NX (where N stands for an integer) is like %X,
but takes up at least N (a number) positions.
The modifiers are `E' and `O'.  For certain characters X,
%EX is a locale's alternative version of %X;
%OX is like %X, but uses the locale's number symbols.

For example, to produce full ISO 8601 format, use "%Y-%m-%dT%T%z".

Popular posts from this blog

11 Years of Writing About Emacs

does md5 creates more randomness?

Google Code shutting down, future of ErgoEmacs