.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
.\"
.\" 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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    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
.\"
.\" Required to disable full justification in groff 1.23.0.
.if n .ds AD l
.\" ========================================================================
.\"
.IX Title "Date::Format 3"
.TH Date::Format 3 2026-03-22 "perl v5.42.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 ASCII strings. They
correspond to the C library routines \f(CW\*(C`strftime\*(C'\fR and \f(CW\*(C`ctime\*(C'\fR.
.IP "time2str(TEMPLATE, TIME [, ZONE [, LANGUAGE]])" 4
.IX Item "time2str(TEMPLATE, TIME [, ZONE [, LANGUAGE]])"
\&\f(CW\*(C`time2str\*(C'\fR converts \f(CW\*(C`TIME\*(C'\fR into an ASCII 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(TEMPLATE, TIME [, ZONE])" 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(TIME [, ZONE])" 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(TIME [, ZONE])" 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   LC_TIME
category of the program\*(Aqs 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 GMT to
2038\-01\-19 03:14:07 GMT.
.SH AUTHOR
.IX Header "AUTHOR"
Graham Barr <gbarr@pobox.com>
.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 <gbarr@pobox.com>
.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.