The cl-strftime Reference Manual

Table of Contents

The cl-strftime Reference Manual

This is the cl-strftime Reference Manual, generated automatically by Declt version 3.0 "Montgomery Scott" on Wed Oct 13 10:12:26 2021 GMT+0.

1 Introduction

CL-STRFTIME is a Common Lisp compiler for the strftime “language.”

FORMAT-TIME takes four arguments: a stream, a strftime-style control
string, a time (defaults to now), and a time zone (defaults to here).

     (cl-strftime:format-time t "%D" (get-universal-time))
     => 02/12/12

The stream argument may be NIL or T, as for FORMAT.

The time argument may be a universal time or a LOCAL-TIME timestamp.

The time zone should be NIL, for here; T, for UTC; or a time zone
object in LOCAL-TIME'S format.

The other exported function, MAKE-TIME-FORMATTER, is to FORMAT-TIME as
FORMATTER is to FORMAT.

FORMAT-TIME also understands a number of named formats. To use a named
format, pass a keyword in place of the control string.

     (cl-strftime:format-time t :rfc-3339 (get-universal-time))
     => 2012-03-19T06:16:29Z

FORMAT-TIME understands the following flags and directives:

FLAGS

- Do not pad
_ Pad with spaces
0 Pad with zeros
# Toggle case
^ Upcase

DIRECTIVES

%% Literal percent sign
%A Weekday (Sunday)
%a Abbreviated weekday (Sun)
%B Month (January)
%b Abbreviated month (Jan)
%C Century (20)
%d Day of month (01-31)
%D Same as %m/%d/%y
%e Same as %_2d
%F Same as %Y-%m-%d
%G ISO 8601 year
%g ISO 8601 year in century
%h Same as %b
%H Hour (01–24)
%I Hour (01–12)
%j Day of year (001-366)
%k Hour ( 1-24)
%l Hour ( 1-12)
%m Month (01-12)
%M Minute (00-59)
%n Literal newline
%p AM or PM
%P am or pm
%r Same as %I:%M:%S %p
%R Same as %H:%M
%s Epoch time
%S Second (00-59)
%t Literal tab
%T Same as %H:%M:%S
%u Day of week (weeks start on Monday)
%U Week number
%V ISO 8601 week number
%w Day of week
%W Week number (weeks start on Monday)
%y Year of century (12)
%Y Year (2012)
%z RFC 2822 timezone
%Z Name of timezone

NAMED FORMATS

(Formats on the same line are synonyms.)

:ARPA :EMAIL :RFC-822
:ASCTIME :CTIME
:COOKIE
:HTTP :RFC-2616
:NEWS :RFC-850 :USENET
:RSS :RFC-2822 :RFC-1036 :RFC-2086
:RFC-1132
:UNIX
:W3C :HTML :RFC-3339 :XML :ATOM

CL-STRFTIME goes to great lengths to be compatible with strftime. In
fact it uses generative testing to ensure its results match those
generated by `date`.

2 Systems

The main system appears first, followed by any subsystem dependency.

2.1 cl-strftime

Author

Paul M. Rodriguez <pmr@ruricolist.com>

License

MIT

Description

Common Lisp compiler for the strftime language.

Dependencies

• alexandria
• serapeum
• cl-ppcre
• local-time

Source

cl-strftime.asd (file)

Components

• package.lisp (file)
• time.lisp (file)
• directives.lisp (file)
• named-format.lisp (file)
• math.lisp (file)
• cl-strftime.lisp (file)

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.

3.1 Lisp

3.1.1 cl-strftime.asd

Location

cl-strftime.asd

Systems

cl-strftime (system)

3.1.2 cl-strftime/package.lisp

Parent

cl-strftime (system)

Location

package.lisp

Packages

cl-strftime

3.1.3 cl-strftime/time.lisp

Dependency

package.lisp (file)

Parent

cl-strftime (system)

Location

time.lisp

Internal Definitions

• +storage-for-deflex-var-am/pm-hours+ (constant)
• +storage-for-deflex-var-century-years+ (constant)
• +storage-for-deflex-var-day-hours+ (constant)
• +storage-for-deflex-var-gmt+ (constant)
• +storage-for-deflex-var-gregorian-cycle+ (constant)
• +storage-for-deflex-var-hour-seconds+ (constant)
• +storage-for-deflex-var-leap-year-days+ (constant)
• +storage-for-deflex-var-month-days+ (constant)
• +storage-for-deflex-var-utc+ (constant)
• +storage-for-deflex-var-week-days+ (constant)
• +storage-for-deflex-var-year-days+ (constant)
• +storage-for-deflex-var-year-months+ (constant)
• +storage-for-deflex-var-zulu+ (constant)
• am/pm-hours (symbol macro)
• century-years (symbol macro)
• day (type)
• day-hours (symbol macro)
• gmt (symbol macro)
• gregorian-cycle (symbol macro)
• hour (type)
• hour-seconds (symbol macro)
• iso-long-year-table (symbol macro)
• iso-long-year? (function)
• iso-week (type)
• last-week (function)
• leap-year-days (symbol macro)
• minute (type)
• month (type)
• month-days (symbol macro)
• month-lengths (symbol macro)
• month-name (function)
• month-offset (function)
• month-offsets (symbol macro)
• months (symbol macro)
• second (type)
• short-month-name (function)
• short-months (symbol macro)
• short-weekday-name (function)
• short-weekdays (symbol macro)
• time (type)
• time-zone (type)
• universal-time (type)
• utc (symbol macro)
• week (type)
• week-days (symbol macro)
• weekday (type)
• weekday-name (function)
• weekdays (symbol macro)
• year (type)
• year-days (symbol macro)
• year-months (symbol macro)
• zulu (symbol macro)

3.1.4 cl-strftime/directives.lisp

Dependency

time.lisp (file)

Parent

cl-strftime (system)

Location

directives.lisp

Internal Definitions

• directive-action (type)
• find-directive (function)
• flag (type)
• time-directives (symbol macro)

3.1.5 cl-strftime/named-format.lisp

Dependency

directives.lisp (file)

Parent

cl-strftime (system)

Location

named-format.lisp

Internal Definitions

• named-time-format (function)
• named-time-formats (symbol macro)

3.1.6 cl-strftime/math.lisp

Dependency

named-format.lisp (file)

Parent

cl-strftime (system)

Location

math.lisp

Internal Definitions

• am/pm (function)
• am/pm-lowercase (function)
• century-of-year (function)
• day-of-year-number (function)
• extract-time-zone-abbrev (function)
• iso-8601-week-number (function)
• iso-8601-year (function)
• iso-8601-year-of-century (function)
• iso-day-of-week (function)
• iso-week+year (function)
• leap-year? (function)
• monday-week-number (function)
• o-clock (function)
• sunday-week-number (function)
• time-zone-name (function)
• time-zone-offset (function)
• time-zone-offset-with-colon (function)
• timestamp-day-of-year (function)
• week-number (function)
• year-of-century (function)

3.1.7 cl-strftime/cl-strftime.lisp

Dependency

math.lisp (file)

Parent

cl-strftime (system)

Location

cl-strftime.lisp

Exported Definitions

• format-time (compiler macro)
• format-time (function)
• make-time-formatter (function)

Internal Definitions

• *compiled-time-formats* (special variable)
• *default-width* (special variable)
• compile-directive (function)
• compile-flag (function)
• compile-flag-char (function)
• compile-formatter (function)
• compile-parsed-format (function)
• expand-tz (function)
• flatten! (function)
• make-time-formatter-1 (function)
• parse-format-string (function)
• writer (type)

4 Packages

Packages are listed by definition order.

4.1 cl-strftime

Source

package.lisp (file)

Use List

• local-time
• serapeum
• alexandria
• common-lisp

Exported Definitions

• format-time (compiler macro)
• format-time (function)
• make-time-formatter (function)

Internal Definitions

• *compiled-time-formats* (special variable)
• *default-width* (special variable)
• +storage-for-deflex-var-am/pm-hours+ (constant)
• +storage-for-deflex-var-century-years+ (constant)
• +storage-for-deflex-var-day-hours+ (constant)
• +storage-for-deflex-var-gmt+ (constant)
• +storage-for-deflex-var-gregorian-cycle+ (constant)
• +storage-for-deflex-var-hour-seconds+ (constant)
• +storage-for-deflex-var-leap-year-days+ (constant)
• +storage-for-deflex-var-month-days+ (constant)
• +storage-for-deflex-var-utc+ (constant)
• +storage-for-deflex-var-week-days+ (constant)
• +storage-for-deflex-var-year-days+ (constant)
• +storage-for-deflex-var-year-months+ (constant)
• +storage-for-deflex-var-zulu+ (constant)
• am/pm (function)
• am/pm-hours (symbol macro)
• am/pm-lowercase (function)
• century-of-year (function)
• century-years (symbol macro)
• compile-directive (function)
• compile-flag (function)
• compile-flag-char (function)
• compile-formatter (function)
• compile-parsed-format (function)
• day (type)
• day-hours (symbol macro)
• day-of-year-number (function)
• directive-action (type)
• expand-tz (function)
• extract-time-zone-abbrev (function)
• find-directive (function)
• flag (type)
• flatten! (function)
• gmt (symbol macro)
• gregorian-cycle (symbol macro)
• hour (type)
• hour-seconds (symbol macro)
• iso-8601-week-number (function)
• iso-8601-year (function)
• iso-8601-year-of-century (function)
• iso-day-of-week (function)
• iso-long-year-table (symbol macro)
• iso-long-year? (function)
• iso-week (type)
• iso-week+year (function)
• last-week (function)
• leap-year-days (symbol macro)
• leap-year? (function)
• make-time-formatter-1 (function)
• minute (type)
• monday-week-number (function)
• month (type)
• month-days (symbol macro)
• month-lengths (symbol macro)
• month-name (function)
• month-offset (function)
• month-offsets (symbol macro)
• months (symbol macro)
• named-time-format (function)
• named-time-formats (symbol macro)
• o-clock (function)
• parse-format-string (function)
• second (type)
• short-month-name (function)
• short-months (symbol macro)
• short-weekday-name (function)
• short-weekdays (symbol macro)
• sunday-week-number (function)
• time (type)
• time-directives (symbol macro)
• time-zone (type)
• time-zone-name (function)
• time-zone-offset (function)
• time-zone-offset-with-colon (function)
• timestamp-day-of-year (function)
• universal-time (type)
• utc (symbol macro)
• week (type)
• week-days (symbol macro)
• week-number (function)
• weekday (type)
• weekday-name (function)
• weekdays (symbol macro)
• writer (type)
• year (type)
• year-days (symbol macro)
• year-months (symbol macro)
• year-of-century (function)
• zulu (symbol macro)

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.

5.1 Exported definitions

5.1.1 Compiler macros

Compiler Macro: format-time STREAM FORMAT &optional TIME TZ

Package

cl-strftime

Source

cl-strftime.lisp (file)

5.1.2 Functions

Function: format-time STREAM FORMAT &optional TIME TZ

Write TIME to STREAM as instructed by FORMAT.

TZ may be ‘nil’ (for the current default timezone), ‘t’ (for GMT), or an object of type ‘local-time::timezone’.

FLAGS

- Do not pad
_ Pad with spaces
0 Pad with zeros
# Toggle case
^ Upcase

DIRECTIVES

%% Literal percent sign
%A Weekday (Sunday)
%a Abbreviated weekday (Sun)
%B Month (January)
%b Abbreviated month (Jan)
%C Century (20)
%d Day of month (01-31)
%D Same as %m/%d/%y
%e Same as %_2d
%F Same as %Y-%m-%d
%G ISO 8601 year
%g ISO 8601 year in century
%h Same as %b
%H Hour (01–24)
%I Hour (01–12)
%j Day of year (001-366)
%k Hour ( 1-24)
%l Hour ( 1-12)
%m Month (01-12)
%M Minute (00-59)
%n Literal newline
%p AM or PM
%P am or pm
%r Same as %I:%M:%S %p
%R Same as %H:%M
%s Epoch time
%S Second (00-59)
%t Literal tab
%T Same as %H:%M:%S
%u Day of week (weeks start on Monday)
%U Week number
%V ISO 8601 week number
%w Day of week
%W Week number (weeks start on Monday)
%y Year of century (12)
%Y Year (2012)
%z RFC 2822 timezone
%Z Name of timezone

NAMED FORMATS

(Formats on the same line are synonyms.)

:ARPA :EMAIL :RFC-822
:ASCTIME :CTIME
:COOKIE
:HTTP :RFC-2616
:NEWS :RFC-850 :USENET
:RSS :RFC-2822 :RFC-1036 :RFC-2086
:RFC-1132
:UNIX
:W3C :HTML :RFC-3339 :XML :ATOM

Package

cl-strftime

Source

cl-strftime.lisp (file)

Function: make-time-formatter FORMAT

Package

cl-strftime

Source

cl-strftime.lisp (file)

5.2 Internal definitions

5.2.1 Constants

Constant: +storage-for-deflex-var-am/pm-hours+

Hours ante/post meridian.

Package

cl-strftime

Source

time.lisp (file)

Constant: +storage-for-deflex-var-century-years+

Years in a century.

Package

cl-strftime

Source

time.lisp (file)

Constant: +storage-for-deflex-var-day-hours+

Hours in a day.

Package

cl-strftime

Source

time.lisp (file)

Constant: +storage-for-deflex-var-gmt+

Package

cl-strftime

Source

time.lisp (file)

Constant: +storage-for-deflex-var-gregorian-cycle+

Length of a cycle in the Gregorian calendar.

Package

cl-strftime

Source

time.lisp (file)

Constant: +storage-for-deflex-var-hour-seconds+

Seconds in an hour.

Package

cl-strftime

Source

time.lisp (file)

Constant: +storage-for-deflex-var-leap-year-days+

Days in a leap year.

Package

cl-strftime

Source

time.lisp (file)

Constant: +storage-for-deflex-var-month-days+

Maximum number of days in a month.

Package

cl-strftime

Source

time.lisp (file)

Constant: +storage-for-deflex-var-utc+

Package

cl-strftime

Source

time.lisp (file)

Constant: +storage-for-deflex-var-week-days+

Days in a week.

Package

cl-strftime

Source

time.lisp (file)

Constant: +storage-for-deflex-var-year-days+

Days in a (non-leap) year.

Package

cl-strftime

Source

time.lisp (file)

Constant: +storage-for-deflex-var-year-months+

Months in a year.

Package

cl-strftime

Source

time.lisp (file)

Constant: +storage-for-deflex-var-zulu+

Package

cl-strftime

Source

time.lisp (file)

5.2.2 Special variables

Special Variable: *compiled-time-formats*

Package

cl-strftime

Source

cl-strftime.lisp (file)

Special Variable: *default-width*

Package

cl-strftime

Source

cl-strftime.lisp (file)

5.2.3 Symbol macros

Symbol Macro: am/pm-hours

Package

cl-strftime

Source

time.lisp (file)

Expansion

cl-strftime::+storage-for-deflex-var-am/pm-hours+

Symbol Macro: century-years

Package

cl-strftime

Source

time.lisp (file)

Expansion

cl-strftime::+storage-for-deflex-var-century-years+

Symbol Macro: day-hours

Package

cl-strftime

Source

time.lisp (file)

Expansion

cl-strftime::+storage-for-deflex-var-day-hours+

Symbol Macro: gmt

Package

cl-strftime

Source

time.lisp (file)

Expansion

cl-strftime::+storage-for-deflex-var-gmt+

Symbol Macro: gregorian-cycle

Package

cl-strftime

Source

time.lisp (file)

Expansion

cl-strftime::+storage-for-deflex-var-gregorian-cycle+

Symbol Macro: hour-seconds

Package

cl-strftime

Source

time.lisp (file)

Expansion

cl-strftime::+storage-for-deflex-var-hour-seconds+

Symbol Macro: iso-long-year-table

Package

cl-strftime

Source

time.lisp (file)

Expansion

cl-strftime::*storage-for-deflex-var-iso-long-year-table*

Symbol Macro: leap-year-days

Package

cl-strftime

Source

time.lisp (file)

Expansion

cl-strftime::+storage-for-deflex-var-leap-year-days+

Symbol Macro: month-days

Package

cl-strftime

Source

time.lisp (file)

Expansion

cl-strftime::+storage-for-deflex-var-month-days+

Symbol Macro: month-lengths

Package

cl-strftime

Source

time.lisp (file)

Expansion

cl-strftime::*storage-for-deflex-var-month-lengths*

Symbol Macro: month-offsets

Package

cl-strftime

Source

time.lisp (file)

Expansion

cl-strftime::*storage-for-deflex-var-month-offsets*

Symbol Macro: months

Package

cl-strftime

Source

time.lisp (file)

Expansion

cl-strftime::*storage-for-deflex-var-months*

Symbol Macro: named-time-formats

Package

cl-strftime

Source

named-format.lisp (file)

Expansion

cl-strftime::*storage-for-deflex-var-named-time-formats*

Symbol Macro: short-months

Package

cl-strftime

Source

time.lisp (file)

Expansion

cl-strftime::*storage-for-deflex-var-short-months*

Symbol Macro: short-weekdays

Package

cl-strftime

Source

time.lisp (file)

Expansion

cl-strftime::*storage-for-deflex-var-short-weekdays*

Symbol Macro: time-directives

Package

cl-strftime

Source

directives.lisp (file)

Expansion

cl-strftime::*storage-for-deflex-var-time-directives*

Symbol Macro: utc

Package

cl-strftime

Source

time.lisp (file)

Expansion

cl-strftime::+storage-for-deflex-var-utc+

Symbol Macro: week-days

Package

cl-strftime

Source

time.lisp (file)

Expansion

cl-strftime::+storage-for-deflex-var-week-days+

Symbol Macro: weekdays

Package

cl-strftime

Source

time.lisp (file)

Expansion

cl-strftime::*storage-for-deflex-var-weekdays*

Symbol Macro: year-days

Package

cl-strftime

Source

time.lisp (file)

Expansion

cl-strftime::+storage-for-deflex-var-year-days+

Symbol Macro: year-months

Package

cl-strftime

Source

time.lisp (file)

Expansion

cl-strftime::+storage-for-deflex-var-year-months+

Symbol Macro: zulu

Package

cl-strftime

Source

time.lisp (file)

Expansion

cl-strftime::+storage-for-deflex-var-zulu+

5.2.4 Functions

Function: am/pm TIME

Package

cl-strftime

Source

math.lisp (file)

Function: am/pm-lowercase TIME

Package

cl-strftime

Source

math.lisp (file)

Function: century-of-year TIME

Package

cl-strftime

Source

math.lisp (file)

Function: compile-directive FLAG WIDTH DIRECTIVE

Package

cl-strftime

Source

cl-strftime.lisp (file)

Function: compile-flag FLAG WIDTH ACTION

Package

cl-strftime

Source

cl-strftime.lisp (file)

Function: compile-flag-char FLAG-CHAR WIDTH ACTION

Package

cl-strftime

Source

cl-strftime.lisp (file)

Function: compile-formatter STRING

Package

cl-strftime

Source

cl-strftime.lisp (file)

Function: compile-parsed-format FORMAT

Package

cl-strftime

Source

cl-strftime.lisp (file)

Function: day-of-year-number Y M D

Package

cl-strftime

Source

math.lisp (file)

Function: expand-tz TZ

Package

cl-strftime

Source

cl-strftime.lisp (file)

Function: extract-time-zone-abbrev TIME

Package

cl-strftime

Source

math.lisp (file)

Function: find-directive CHAR &key NOERROR

Package

cl-strftime

Source

directives.lisp (file)

Function: flatten! LIST

Package

cl-strftime

Source

cl-strftime.lisp (file)

Function: iso-8601-week-number TIME

Package

cl-strftime

Source

math.lisp (file)

Function: iso-8601-year TIME

Package

cl-strftime

Source

math.lisp (file)

Function: iso-8601-year-of-century TIME

Package

cl-strftime

Source

math.lisp (file)

Function: iso-day-of-week TIME

Return the day of week from 1–7, where 1 is Monday.

Package

cl-strftime

Source

math.lisp (file)

Function: iso-long-year? YEAR

Package

cl-strftime

Source

time.lisp (file)

Function: iso-week+year TIME

Package

cl-strftime

Source

math.lisp (file)

Function: last-week YEAR

Package

cl-strftime

Source

time.lisp (file)

Function: leap-year? Y

Package

cl-strftime

Source

math.lisp (file)

Function: make-time-formatter-1 FORMAT FORCE-GMT

Package

cl-strftime

Source

cl-strftime.lisp (file)

Function: monday-week-number TIME

Package

cl-strftime

Source

math.lisp (file)

Function: month-name TIME

Package

cl-strftime

Source

time.lisp (file)

Function: month-offset M

Package

cl-strftime

Source

time.lisp (file)

Function: named-time-format NAME &optional GMT?

Package

cl-strftime

Source

named-format.lisp (file)

Function: o-clock TIME

Package

cl-strftime

Source

math.lisp (file)

Function: parse-format-string STRING

Package

cl-strftime

Source

cl-strftime.lisp (file)

Function: short-month-name TIME

Package

cl-strftime

Source

time.lisp (file)

Function: short-weekday-name TIME

Package

cl-strftime

Source

time.lisp (file)

Function: sunday-week-number TIME

Package

cl-strftime

Source

math.lisp (file)

Function: time-zone-name TIME &optional NATO

Package

cl-strftime

Source

math.lisp (file)

Function: time-zone-offset TIME

Package

cl-strftime

Source

math.lisp (file)

Function: time-zone-offset-with-colon TIME

Package

cl-strftime

Source

math.lisp (file)

Function: timestamp-day-of-year TIME

The day of year of TIME, counting from 1.

Package

cl-strftime

Source

math.lisp (file)

Function: week-number TIME DAY-OF-WEEK

Package

cl-strftime

Source

math.lisp (file)

Function: weekday-name TIME

Package

cl-strftime

Source

time.lisp (file)

Function: year-of-century TIME

Package

cl-strftime

Source

math.lisp (file)

5.2.5 Types

Type: day ()

A day of the month.

Package

cl-strftime

Source

time.lisp (file)

Type: directive-action ()

Package

cl-strftime

Source

directives.lisp (file)

Type: flag ()

Package

cl-strftime

Source

directives.lisp (file)

Type: hour ()

An hour.

Package

cl-strftime

Source

time.lisp (file)

Type: iso-week ()

Package

cl-strftime

Source

time.lisp (file)

Type: minute ()

A minute.

Package

cl-strftime

Source

time.lisp (file)

Type: month ()

A month.

Package

cl-strftime

Source

time.lisp (file)

Type: second ()

A minute.

Package

cl-strftime

Source

time.lisp (file)

Type: time ()

Package

cl-strftime

Source

time.lisp (file)

Type: time-zone ()

Package

cl-strftime

Source

time.lisp (file)

Type: universal-time ()

Package

cl-strftime

Source

time.lisp (file)

Type: week ()

A week of the year.

Package

cl-strftime

Source

time.lisp (file)

Type: weekday ()

A day of the week.

Package

cl-strftime

Source

time.lisp (file)

Type: writer ()

Package

cl-strftime

Source

cl-strftime.lisp (file)

Type: year ()

A year.

Package

cl-strftime

Source

time.lisp (file)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types