.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Date::Format 3"
.TH Date::Format 3 "2026-03-21" "perl v5.32.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Date::Format \- Date formatting subroutines
.SH "VERSION"
.IX Header "VERSION"
version 2.35
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use Date::Format;
\&
\& my @lt = localtime(time);
\&
\& my $template = "....";
\&
\& print time2str($template, time);
\& print strftime($template, @lt);
\&
\& my $zone;
\& print time2str($template, time, $zone);
\& print strftime($template, @lt, $zone);
\&
\& print ctime(time);
\& print asctime(@lt);
\&
\& print ctime(time, $zone);
\& print asctime(@lt, $zone);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module provides routines to format dates into \s-1ASCII\s0 strings. They
correspond to the C library routines \f(CW\*(C`strftime\*(C'\fR and \f(CW\*(C`ctime\*(C'\fR.
.IP "time2str(\s-1TEMPLATE, TIME\s0 [, \s-1ZONE\s0 [, \s-1LANGUAGE\s0]])" 4
.IX Item "time2str(TEMPLATE, TIME [, ZONE [, LANGUAGE]])"
\&\f(CW\*(C`time2str\*(C'\fR converts \f(CW\*(C`TIME\*(C'\fR into an \s-1ASCII\s0 string using the conversion
specification given in \f(CW\*(C`TEMPLATE\*(C'\fR. \f(CW\*(C`ZONE\*(C'\fR if given specifies the zone
which the output is required to be in, \f(CW\*(C`ZONE\*(C'\fR defaults to your current zone.
\&\f(CW\*(C`LANGUAGE\*(C'\fR if given specifies the language for day and month names
(e.g. \f(CW\*(AqGerman\*(Aq\fR, \f(CW\*(AqFrench\*(Aq\fR); defaults to \f(CW\*(AqEnglish\*(Aq\fR.
.IP "strftime(\s-1TEMPLATE, TIME\s0 [, \s-1ZONE\s0])" 4
.IX Item "strftime(TEMPLATE, TIME [, ZONE])"
\&\f(CW\*(C`strftime\*(C'\fR is similar to \f(CW\*(C`time2str\*(C'\fR with the exception that the time is
passed as an array, such as the array returned by \f(CW\*(C`localtime\*(C'\fR.
.IP "ctime(\s-1TIME\s0 [, \s-1ZONE\s0])" 4
.IX Item "ctime(TIME [, ZONE])"
\&\f(CW\*(C`ctime\*(C'\fR calls \f(CW\*(C`time2str\*(C'\fR with the given arguments using the
conversion specification \f(CW"%a %b %e %T %Y\en"\fR
.IP "asctime(\s-1TIME\s0 [, \s-1ZONE\s0])" 4
.IX Item "asctime(TIME [, ZONE])"
\&\f(CW\*(C`asctime\*(C'\fR calls \f(CW\*(C`time2str\*(C'\fR with the given arguments using the
conversion specification \f(CW"%a %b %e %T %Y\en"\fR
.SH "NAME"
Date::Format \- Date formatting subroutines
.SH "MULTI-LANGUAGE SUPPORT"
.IX Header "MULTI-LANGUAGE SUPPORT"
Date::Format is capable of formatting into several languages. You can
pass an optional language name directly to \f(CW\*(C`time2str\*(C'\fR:
.PP
.Vb 2
\& time2str("%a %b %e %T %Y\en", time, undef, \*(AqGerman\*(Aq);
\& time2str("%a %b %e %T %Y\en", time, \*(AqGMT\*(Aq, \*(AqFrench\*(Aq);
.Ve
.PP
Alternatively, create a language-specific object and call methods on it,
see Date::Language:
.PP
.Vb 2
\& my $lang = Date::Language\->new(\*(AqGerman\*(Aq);
\& $lang\->time2str("%a %b %e %T %Y\en", time);
.Ve
.SH "CONVERSION SPECIFICATION"
.IX Header "CONVERSION SPECIFICATION"
Each conversion specification is replaced by appropriate
characters as described in the following list. The
appropriate characters are determined by the \s-1LC_TIME\s0
category of the program's locale.
.PP
.Vb 10
\& %% PERCENT
\& %a day of the week abbr
\& %A day of the week
\& %b month abbr
\& %B month
\& %c MM/DD/YY HH:MM:SS
\& %C ctime format: Sat Nov 19 21:05:57 1994
\& %d numeric day of the month, with leading zeros (eg 01..31)
\& %e like %d, but a leading zero is replaced by a space (eg 1..32)
\& %D MM/DD/YY
\& %G GPS week number (weeks since January 6, 1980)
\& %h month abbr
\& %H hour, 24 hour clock, leading 0\*(Aqs)
\& %I hour, 12 hour clock, leading 0\*(Aqs)
\& %j day of the year
\& %k hour
\& %l hour, 12 hour clock
\& %L month number, starting with 1
\& %m month number, starting with 01
\& %M minute, leading 0\*(Aqs
\& %n NEWLINE
\& %o ornate day of month \-\- "1st", "2nd", "25th", etc.
\& %p AM or PM
\& %P am or pm (Yes %p and %P are backwards :)
\& %q Quarter number, starting with 1
\& %r time format: 09:05:57 PM
\& %R time format: 21:05
\& %s seconds since the Epoch, UCT
\& %S seconds, leading 0\*(Aqs
\& %t TAB
\& %T time format: 21:05:57
\& %U week number, Sunday as first day of week
\& %w day of the week, numerically, Sunday == 0
\& %W week number, Monday as first day of week
\& %x date format: 11/19/94
\& %X time format: 21:05:57
\& %y year (2 digits)
\& %Y year (4 digits)
\& %Z timezone in ascii. eg: PST
\& %z timezone in format \-/+0000
.Ve
.PP
\&\f(CW%d\fR, \f(CW%e\fR, \f(CW%H\fR, \f(CW%I\fR, \f(CW%j\fR, \f(CW%k\fR, \f(CW%l\fR, \f(CW%m\fR, \f(CW%M\fR, \f(CW%q\fR,
\&\f(CW%y\fR and \f(CW%Y\fR can be output in Roman numerals by prefixing the letter
with \f(CW\*(C`O\*(C'\fR, e.g. \f(CW%OY\fR will output the year as roman numerals.
.SH "LIMITATION"
.IX Header "LIMITATION"
The functions in this module are limited to the time range that can be
represented by the time_t data type, i.e. 1901\-12\-13 20:45:53 \s-1GMT\s0 to
2038\-01\-19 03:14:07 \s-1GMT.\s0
.SH "AUTHOR"
.IX Header "AUTHOR"
Graham Barr <[email protected]>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 1995\-2009 Graham Barr. This program is free
software; you can redistribute it and/or modify it under the same terms
as Perl itself.
.SH "AUTHOR"
.IX Header "AUTHOR"
Graham <[email protected]>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2020 by Graham Barr.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.