locale-format-time

Arguments: stream date-time show-date show-time &optional (locale *locale*)fmt

Arguments:

• stream is a stream.
• date-time is a universal-time (see get-universal-time) or a date-time object (see date-time).
• show-date is a boolean.
• show-time is a boolean.
• locale is a locale.
• fmt is a keyword, string, or a list.

This function outputs to the stream a locale appropriate representation of the time specified by date-time. The output format can be specified as a string following the XPG4 strftime() format (see below). If fmt is non-nil, then the date and time booleans are ignored. Otherwise, if fmt is nil, then the date and time booleans determine the format based on the following table:

The function locale-format-time can be invoked using the format ~/ directive. The locale argument can be supplied using format's ~v prefix argument. The fmt argument can be supplied as the second prefix argument. The show-date argument is specified using the colon modifier. The show-time argument is specified using the at-sign modifier.

The LC_TIME category defines display formats using conversion specifications which are also defined in the category. The conversion specifications consist of a '%' followed by one or two letters. The formats are intended for the XPG4 strftime() function.

The locale-format-time function outputs the date/time as specified by the format string in the same way as strftime(). In addition to the field descriptor definitions, the locale-format-time function will interpret the following C escape sequences as follows:

 \\	insert #\\
 \a	insert #\bell
 \b	insert #\backspace
 \f	insert #\page
 \n	insert #\linefeed
 \r	insert #\return
 \t	insert #\tab
 \v	insert #\vt

These are the field descriptor definitions:

  %%      same as %
  %a      locale's abbreviated weekday name
  %A      locale's full weekday name
  %b      locale's abbreviated month name (equivalent to %h)
  %B      locale's full month name
  %c      locale's appropriate date and time representation
  %C      century number (the year divided by  100  and  truncated  
          to  an  integer  as a decimal number [1,99]);
          single digits are preceded by 0
  %d      day of month [1,31]; single digits are preceded by 0
  %D      date as %m/%d/%y
  %e      day of month [1,31]; single digits are preceded by a
          space
  %F      equivalent to %Y-%m-%d
  %G      The ISO 8601 year with century as a decimal number.  
          The 4-digit year corresponding to the ISO week number 
          (see %V).  This has the same format and value as %y, 
          except that if the ISO week number belongs to the 
          previous or next year, that year is used instead.
  %g      Like %G, but without century, i.e., with a 2-digit year (00-99)  
  %h      locale's abbreviated month name (equivalent to %b)
  %H      hour (24-hour clock) [0,23]; single digits are preceded 
          by 0
  %I      hour (12-hour clock) [1,12]; single digits are preceded
          by 0
  %j      day number of year [001,366];
  %k      hour (24-hour clock) [0,23]; single digits are  
          preceded by a blank
  %l      hour (12-hour clock) [1,12]; single digits are  
          preceded by a blank
  %m      month number [1,12]; single digits are preceded by 0
  %M      minute [00,59]; single digits are preceded by 0
  %n      insert a newline
  %p      locale's equivalent of either a.m. or p.m 
          (case unspecified).
  %P      like %p but case specified to be lowercase
  %r      appropriate time  representation  in  12-hour  clock
          format with %p
  %R      time as %H:%M
  %S      seconds [00,61]
  %t      insert a tab
  %T      time as %H:%M:%S
  %u      weekday as a decimal number [1,7], with 1 representing 
          Monday
  %V      week number of the year as a decimal number [01,53],
          with  Monday  as  the first day of the week.  If the
          week containing 1 January has four or more  days  in
          the  new  year, then it is considered week 1; 
          otherwise, it is week 53 of the previous  year,  and  
          the next week is week 1.
  %w      weekday as a decimal number [0,6], with 0 
          representing Sunday. See also %u.
  %x      locale's appropriate date representation
  %X      locale's appropriate time representation
  %y      year within century [00,99]
  %Y      year, including the century (for example 1993)
  %Z      time zone name or abbreviation, or no  bytes  if  no
          time zone information exists

Modified Conversion Specifications

Some conversion specifications can be modified by the E and O modifiers to indicate that an alternate format or specification should be used rather than the one normally used by the unmodified conversion specification. If the alternate format or specification does not exist in the current locale, the behavior will be as if the unmodified specification were used.

  %Ec     locale's  alternate  appropriate   date   and   time
	  representation
  %EC     name of the  base  year  (period)  in  the  locale's
	  alternate representation
  %Ex     locale's alternate date representation
  %EX     locale's alternate time representation
  %Ey     offset from %EC (year only) in the  locale's  
          alternate representation
  %EY     full alternate year representation
  %Od     day  of  the  month  using  the  locale's  alternate
	  numeric symbols
  %Oe     same as %Od
  %OH     hour (24-hour clock) using  the  locale's  alternate
	  numeric symbols
  %OI     hour (12-hour clock) using  the  locale's  alternate
	  numeric symbols
  %Om     month using the locale's alternate numeric symbols
  %OM     minutes using the locale's alternate numeric symbols
  %OS     seconds using the locale's alternate numeric symbols
  %Ow     number of the weekday (Sunday=0) using the  locale's
	  alternate numeric symbols
  %Oy     year (offset from  %C)  in  the  locale's  alternate
	  representation  and  using  the  locale's  alternate
	  numeric symbols

The fmt argument

The fmt argument can be a string, as specified above; the symbol :secondf, :minutef, or :hourf; a list where each element is either a string or one of the keywords just specified, or a list where the first element of the inner list is either :secondf, :minutef, or :hourf and the second element is an integer specifying the number of fractional digits to be displayed, or a list where the first element is :expanded, the second element is an integer specifying the number of year digits to be displayed (along with a preceeding #\+ or #\- sign), followed by a fmt that displays a year (such as "%G").

Example:

;;  [assuming *locale* is (find-locale "en_US")]

(format t "~/locale-format-time/" 3192624000)
  prints `08:00:00 AM '

(format t "~:/locale-format-time/" 3192624000)
  prints `Saturday, March 03, 2001'

(format t "~@/locale-format-time/" 3192624000)
  prints `08:00:00  '

(format t "~:@/locale-format-time/" 3192624000)
  prints `Saturday, March 03, 2001 08:00:00 AM '

(format t "~v:@/locale-format-time/" :fr_FR 3192624000)
  prints `samedi 03 mars 2001 08 h 00 '

(format t "~v,v:@/locale-format-time/" :fr_FR "%A" 3192624000)
  prints `samedi'

(format t "~,v:@/locale-format-time/" "%A" 3192624000)
  prints `Saturday'

;;  The following examples use date-time representations:

(format t "~,v/locale-format-time/" 
        '(:expanded 3 "%G") (date-time "19850412"))
  prints `+0001985'

;;  The date-time which is the value of D is used in the 
;;  examples below.
(setq d (date-time "19850412T23:20:50,46"))
 
(format t "~,v/locale-format-time/" '((:secondf 1)) d)
  prints `5'  ;; rounds up to fit the number of digits specified
 
(format t "~,v/locale-format-time/" '((:secondf 2)) d)
  prints `46'
 
(format t "~,v/locale-format-time/" '((:secondf 3)) d)
  prints `460'

(format t "~,v/locale-format-time/" '("%H," (:hourf 3)) d)
  prints `23,345'

See Localization support in Allegro CL in iacl.htm.

Copyright (c) 1998-2016, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 8.1 page.
Created 2010.1.21.