ut-to-string-formatter

Function

Package: excl

ToC

DocOverview

CGDoc

RelNotes

FAQ

Index

PermutedIndex

Allegro CL version 8.2
New since 8.2 release.

ut-to-string-formatter

Arguments: string

This function is in the :anydate module, which is autoloaded, if necessary, when this function is called. This function was added by a patch released in May, 2014. You must have updated Allegro CL (see sys:update-allegro) in order to use this function.

This function converts string, containing text and directives, into a function suitable as the value of the format argument to universal-time-to-string when the relative keyword argument to that function is a universal time. The function, which converts relative times to strings, is then returned. The function accepts five arguments: a stream (or t or nil), an integer or ratio indicating seconds, an integer representing minutes, and integer representing hours, and an integer representing days.

The returned function is an interpreted function object. We recommend you compile it (assuming the compiler is available) as in the following example:

(setq f (compile nil (ut-to-string-formatter "%Dd%2Hh%2Mm%2Ss")))

;; Now F can be used as the value of the FORMAT argument:
(universal-time-to-string ut :relative (+ ut (* 40 3666)) :format f)
;; See the examples below for the result of this call.

The string can contain any text and also the following directives (case is important, %d is not the same as %D):

%S - the value of the seconds argument
%M - the value of the minutes argument
%H - the value of the hours argument
%D - the value of the days argument
%p plural for the most recent value printed
%% - the % character (so % can appear in the string)

A "2" can optionally follow the % and preceed the single-letter directive. For example, strings and possible output:

"%H:%M:%S"		"2:1:1"
"%2H:%2M:%2S"		"02:01:01"
"%D day%p, %H hour%p, %M minute%p and %S second%p"
	      	        "1 day, 2 hours, 59 minutes and 10 seconds"
"%Dd%2Hh%2Mm%2Ss"	"15d17h48m20"

See universal-time-to-string, string-to-universal-time, and the General date to universal time parsers section of date-time.htm for more information. The date-time.htm document also describes the date-time module which provides additional ISO-8601 support.

Examples

;; When RELATIVE is a universal time, FORMAT can be unspecified and
;; a suitable formatting function will be used (and so a call to
;; UT-TO-STRING-FORMATTER is not necessary:
(setq ut 3603660634)
(universal-time-to-string ut :relative (+ ut 1 (* 10 3600)))
  => "10:00:01"

;; Compiling the function returned by UT-TO-STRING-FORMATTER improves 
;; efficiency but is not required.
(setq f (compile nil (ut-to-string-formatter "%Dd%2Hh%2Mm%2Ss")))
(universal-time-to-string ut :relative (+ ut (* 40 3666)) :format f)
  => "1d16h44m00"

;; The string argument to UT-TO-STRING-FORMATTER can be passed as the
;; format argument to UNIVERSAL-TIME-TO-STRING with the same result:
(universal-time-to-string ut :relative (+ ut (* 40 3666)) 
                          :format "%Dd%2Hh%2Mm%2Ss")
  => "1d16h44m00"


(setq f (compile nil (ut-to-string-formatter
      		      "%D day%p, %H hour%p, %M minute%p and %S second%p")))
(universal-time-to-string 3603660634
			  :relative (+ 3603660634 (* 41 3666))
			  :format f)
  => "1 day, 17 hours, 45 minutes and 6 seconds"