diff options
Diffstat (limited to 'upstream/archlinux/man3/Time::Piece.3perl')
| -rw-r--r-- | upstream/archlinux/man3/Time::Piece.3perl | 384 |
1 files changed, 384 insertions, 0 deletions
diff --git a/upstream/archlinux/man3/Time::Piece.3perl b/upstream/archlinux/man3/Time::Piece.3perl new file mode 100644 index 00000000..14f80ba1 --- /dev/null +++ b/upstream/archlinux/man3/Time::Piece.3perl @@ -0,0 +1,384 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" 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 +.\" ======================================================================== +.\" +.IX Title "Time::Piece 3perl" +.TH Time::Piece 3perl 2024-02-11 "perl v5.38.2" "Perl Programmers Reference Guide" +.\" 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 +Time::Piece \- Object Oriented time objects +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& use Time::Piece; +\& +\& my $t = localtime; +\& print "Time is $t\en"; +\& print "Year is ", $t\->year, "\en"; +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +This module replaces the standard \f(CW\*(C`localtime\*(C'\fR and \f(CW\*(C`gmtime\*(C'\fR functions with +implementations that return objects. It does so in a backwards +compatible manner, so that using localtime/gmtime in the way documented +in perlfunc will still return what you expect. +.PP +The module actually implements most of an interface described by +Larry Wall on the perl5\-porters mailing list here: +<https://www.nntp.perl.org/group/perl.perl5.porters/2000/01/msg5283.html> +.SH USAGE +.IX Header "USAGE" +After importing this module, when you use localtime or gmtime in a scalar +context, rather than getting an ordinary scalar string representing the +date and time, you get a Time::Piece object, whose stringification happens +to produce the same effect as the localtime and gmtime functions. There is +also a \fBnew()\fR constructor provided, which is the same as \fBlocaltime()\fR, except +when passed a Time::Piece object, in which case it's a copy constructor. The +following methods are available on the object: +.PP +.Vb 10 +\& $t\->sec # also available as $t\->second +\& $t\->min # also available as $t\->minute +\& $t\->hour # 24 hour +\& $t\->mday # also available as $t\->day_of_month +\& $t\->mon # 1 = January +\& $t\->_mon # 0 = January +\& $t\->monname # Feb +\& $t\->month # same as $t\->monname +\& $t\->fullmonth # February +\& $t\->year # based at 0 (year 0 AD is, of course 1 BC) +\& $t\->_year # year minus 1900 +\& $t\->yy # 2 digit year +\& $t\->wday # 1 = Sunday +\& $t\->_wday # 0 = Sunday +\& $t\->day_of_week # 0 = Sunday +\& $t\->wdayname # Tue +\& $t\->day # same as wdayname +\& $t\->fullday # Tuesday +\& $t\->yday # also available as $t\->day_of_year, 0 = Jan 01 +\& $t\->isdst # also available as $t\->daylight_savings +\& +\& $t\->hms # 12:34:56 +\& $t\->hms(".") # 12.34.56 +\& $t\->time # same as $t\->hms +\& +\& $t\->ymd # 2000\-02\-29 +\& $t\->date # same as $t\->ymd +\& $t\->mdy # 02\-29\-2000 +\& $t\->mdy("/") # 02/29/2000 +\& $t\->dmy # 29\-02\-2000 +\& $t\->dmy(".") # 29.02.2000 +\& $t\->datetime # 2000\-02\-29T12:34:56 (ISO 8601) +\& $t\->cdate # Tue Feb 29 12:34:56 2000 +\& "$t" # same as $t\->cdate +\& +\& $t\->epoch # seconds since the epoch +\& $t\->tzoffset # timezone offset in a Time::Seconds object +\& +\& $t\->julian_day # number of days since Julian period began +\& $t\->mjd # modified Julian date (JD\-2400000.5 days) +\& +\& $t\->week # week number (ISO 8601) +\& +\& $t\->is_leap_year # true if it\*(Aqs a leap year +\& $t\->month_last_day # 28\-31 +\& +\& $t\->time_separator($s) # set the default separator (default ":") +\& $t\->date_separator($s) # set the default separator (default "\-") +\& $t\->day_list(@days) # set the default weekdays +\& $t\->mon_list(@days) # set the default months +\& +\& $t\->strftime(FORMAT) # same as POSIX::strftime (without the overhead +\& # of the full POSIX extension) +\& $t\->strftime() # "Tue, 29 Feb 2000 12:34:56 GMT" +\& +\& Time::Piece\->strptime(STRING, FORMAT) +\& # see strptime man page. Creates a new +\& # Time::Piece object +.Ve +.PP +Note that \f(CW\*(C`localtime\*(C'\fR and \f(CW\*(C`gmtime\*(C'\fR are not listed above. If called as +methods on a Time::Piece object, they act as constructors, returning a new +Time::Piece object for the current time. In other words: they're not useful as +methods. +.SS "Local Locales" +.IX Subsection "Local Locales" +Both wdayname (day) and monname (month) allow passing in a list to use +to index the name of the days against. This can be useful if you need +to implement some form of localisation without actually installing or +using locales. Note that this is a global override and will affect +all Time::Piece instances. +.PP +.Vb 1 +\& my @days = qw( Dimanche Lundi Merdi Mercredi Jeudi Vendredi Samedi ); +\& +\& my $french_day = localtime\->day(@days); +.Ve +.PP +These settings can be overridden globally too: +.PP +.Vb 1 +\& Time::Piece::day_list(@days); +.Ve +.PP +Or for months: +.PP +.Vb 1 +\& Time::Piece::mon_list(@months); +.Ve +.PP +And locally for months: +.PP +.Vb 1 +\& print localtime\->month(@months); +.Ve +.PP +Or to populate with your current system locale call: + Time::Piece\->\fBuse_locale()\fR; +.SS "Date Calculations" +.IX Subsection "Date Calculations" +It's possible to use simple addition and subtraction of objects: +.PP +.Vb 1 +\& use Time::Seconds; +\& +\& my $seconds = $t1 \- $t2; +\& $t1 += ONE_DAY; # add 1 day (constant from Time::Seconds) +.Ve +.PP +The following are valid ($t1 and \f(CW$t2\fR are Time::Piece objects): +.PP +.Vb 3 +\& $t1 \- $t2; # returns Time::Seconds object +\& $t1 \- 42; # returns Time::Piece object +\& $t1 + 533; # returns Time::Piece object +.Ve +.PP +However adding a Time::Piece object to another Time::Piece object +will cause a runtime error. +.PP +Note that the first of the above returns a Time::Seconds object, so +while examining the object will print the number of seconds (because +of the overloading), you can also get the number of minutes, hours, +days, weeks and years in that delta, using the Time::Seconds API. +.PP +In addition to adding seconds, there are two APIs for adding months and +years: +.PP +.Vb 2 +\& $t = $t\->add_months(6); +\& $t = $t\->add_years(5); +.Ve +.PP +The months and years can be negative for subtractions. Note that there +is some "strange" behaviour when adding and subtracting months at the +ends of months. Generally when the resulting month is shorter than the +starting month then the number of overlap days is added. For example +subtracting a month from 2008\-03\-31 will not result in 2008\-02\-31 as this +is an impossible date. Instead you will get 2008\-03\-02. This appears to +be consistent with other date manipulation tools. +.SS Truncation +.IX Subsection "Truncation" +Calling the \f(CW\*(C`truncate\*(C'\fR method returns a copy of the object but with the +time truncated to the start of the supplied unit. +.PP +.Vb 1 +\& $t = $t\->truncate(to => \*(Aqday\*(Aq); +.Ve +.PP +This example will set the time to midnight on the same date which \f(CW$t\fR +had previously. Allowed values for the "to" parameter are: "year", +"quarter", "month", "day", "hour", "minute" and "second". +.SS "Date Comparisons" +.IX Subsection "Date Comparisons" +Date comparisons are also possible, using the full suite of "<", ">", +"<=", ">=", "<=>", "==" and "!=". +.SS "Date Parsing" +.IX Subsection "Date Parsing" +Time::Piece has a built-in \fBstrptime()\fR function (from FreeBSD), allowing +you incredibly flexible date parsing routines. For example: +.PP +.Vb 2 +\& my $t = Time::Piece\->strptime("Sunday 3rd Nov, 1943", +\& "%A %drd %b, %Y"); +\& +\& print $t\->strftime("%a, %d %b %Y"); +.Ve +.PP +Outputs: +.PP +.Vb 1 +\& Wed, 03 Nov 1943 +.Ve +.PP +(see, it's even smart enough to fix my obvious date bug) +.PP +For more information see "man strptime", which should be on all unix +systems. +.PP +Alternatively look here: <http://www.unix.com/man\-page/FreeBSD/3/strftime/> +.PP +\fICAVEAT \fR\f(CI%A\fR\fI, \fR\f(CI%a\fR\fI, \fR\f(CI%B\fR\fI, \fR\f(CI%b\fR\fI, and friends\fR +.IX Subsection "CAVEAT %A, %a, %B, %b, and friends" +.PP +Time::Piece::strptime by default can only parse American English date names. +Meanwhile, Time::Piece\->\fBstrftime()\fR will return date names that use the current +configured system locale. This means dates returned by strftime might not be +able to be parsed by strptime. This is the default behavior and can be +overridden by calling Time::Piece\->\fBuse_locale()\fR. This builds a list of the +current locale's day and month names which strptime will use to parse with. +Note this is a global override and will affect all Time::Piece instances. +.PP +For instance with a German locale: +.PP +.Vb 1 +\& localtime\->day_list(); +.Ve +.PP +Returns +.PP +.Vb 1 +\& ( \*(AqSun\*(Aq, \*(AqMon\*(Aq, \*(AqTue\*(Aq, \*(AqWed\*(Aq, \*(AqThu\*(Aq, \*(AqFri\*(Aq, \*(AqSat\*(Aq ) +.Ve +.PP +While: +.PP +.Vb 2 +\& Time::Piece\->use_locale(); +\& localtime\->day_list(); +.Ve +.PP +Returns +.PP +.Vb 1 +\& ( \*(AqSo\*(Aq, \*(AqMo\*(Aq, \*(AqDi\*(Aq, \*(AqMi\*(Aq, \*(AqDo\*(Aq, \*(AqFr\*(Aq, \*(AqSa\*(Aq ) +.Ve +.SS YYYY\-MM\-DDThh:mm:ss +.IX Subsection "YYYY-MM-DDThh:mm:ss" +The ISO 8601 standard defines the date format to be YYYY-MM-DD, and +the time format to be hh:mm:ss (24 hour clock), and if combined, they +should be concatenated with date first and with a capital 'T' in front +of the time. +.SS "Week Number" +.IX Subsection "Week Number" +The \fIweek number\fR may be an unknown concept to some readers. The ISO +8601 standard defines that weeks begin on a Monday and week 1 of the +year is the week that includes both January 4th and the first Thursday +of the year. In other words, if the first Monday of January is the +2nd, 3rd, or 4th, the preceding days of the January are part of the +last week of the preceding year. Week numbers range from 1 to 53. +.SS "Global Overriding" +.IX Subsection "Global Overriding" +Finally, it's possible to override localtime and gmtime everywhere, by +including the ':override' tag in the import list: +.PP +.Vb 1 +\& use Time::Piece \*(Aq:override\*(Aq; +.Ve +.SH CAVEATS +.IX Header "CAVEATS" +.ie n .SS "Setting $ENV{TZ} in Threads on Win32" +.el .SS "Setting \f(CW$ENV\fP{TZ} in Threads on Win32" +.IX Subsection "Setting $ENV{TZ} in Threads on Win32" +Note that when using perl in the default build configuration on Win32 +(specifically, when perl is built with PERL_IMPLICIT_SYS), each perl +interpreter maintains its own copy of the environment and only the main +interpreter will update the process environment seen by strftime. +.PP +Therefore, if you make changes to \f(CW$ENV\fR{TZ} from inside a thread other than +the main thread then those changes will not be seen by strftime if you +subsequently call that with the \f(CW%Z\fR formatting code. You must change \f(CW$ENV\fR{TZ} +in the main thread to have the desired effect in this case (and you must +also call \fB_tzset()\fR in the main thread to register the environment change). +.PP +Furthermore, remember that this caveat also applies to \fBfork()\fR, which is +emulated by threads on Win32. +.SS "Use of epoch seconds" +.IX Subsection "Use of epoch seconds" +This module internally uses the epoch seconds system that is provided via +the perl \f(CWtime()\fR function and supported by \f(CWgmtime()\fR and \f(CWlocaltime()\fR. +.PP +If your perl does not support times larger than \f(CW\*(C`2^31\*(C'\fR seconds then this +module is likely to fail at processing dates beyond the year 2038. There are +moves afoot to fix that in perl. Alternatively use 64 bit perl. Or if none +of those are options, use the DateTime module which has support for years +well into the future and past. +.PP +Also, the internal representation of Time::Piece\->strftime deviates from the +standard POSIX implementation in that is uses the epoch (instead of separate +year, month, day parts). This change was added in version 1.30. If you must +have a more traditional strftime (which will normally never calculate day +light saving times correctly), you can pass the date parts from Time::Piece +into the strftime function provided by the POSIX module +(see strftime in POSIX ). +.SH AUTHOR +.IX Header "AUTHOR" +Matt Sergeant, matt@sergeant.org +Jarkko Hietaniemi, jhi@iki.fi (while creating Time::Piece for core perl) +.SH "COPYRIGHT AND LICENSE" +.IX Header "COPYRIGHT AND LICENSE" +Copyright 2001, Larry Wall. +.PP +This module is free software, you may distribute it under the same terms +as Perl. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +The excellent Calendar FAQ at <http://www.tondering.dk/claus/calendar.html> +.SH BUGS +.IX Header "BUGS" +The test harness leaves much to be desired. Patches welcome. |