{ "content": [ { "type": "text", "text": "# Time::Piece (perldoc)\n\n## NAME\n\nTime::Piece - Object Oriented time objects\n\n## SYNOPSIS\n\nuse Time::Piece;\nmy $t = localtime;\nprint \"Time is $t\\n\";\nprint \"Year is \", $t->year, \"\\n\";\n\n## DESCRIPTION\n\nThis module replaces the standard \"localtime\" and \"gmtime\" functions with implementations that\nreturn objects. It does so in a backwards compatible manner, so that using localtime/gmtime in\nthe way documented in perlfunc will still return what you expect.\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION**\n- **USAGE** (7 subsections)\n- **CAVEATS** (1 subsections)\n- **AUTHOR**\n- **COPYRIGHT AND LICENSE**\n- **SEE ALSO**\n- **BUGS**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "Time::Piece", "section": "", "mode": "perldoc", "summary": "Time::Piece - Object Oriented time objects", "synopsis": "use Time::Piece;\nmy $t = localtime;\nprint \"Time is $t\\n\";\nprint \"Year is \", $t->year, \"\\n\";", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 6, "subsections": [] }, { "name": "DESCRIPTION", "lines": 7, "subsections": [] }, { "name": "USAGE", "lines": 70, "subsections": [ { "name": "Local Locales", "lines": 23 }, { "name": "Date Calculations", "lines": 31 }, { "name": "Truncation", "lines": 9 }, { "name": "Date Comparisons", "lines": 3 }, { "name": "Date Parsing", "lines": 48 }, { "name": "Week Number", "lines": 6 }, { "name": "Global Overriding", "lines": 5 } ] }, { "name": "CAVEATS", "lines": 13, "subsections": [ { "name": "Use of epoch seconds", "lines": 14 } ] }, { "name": "AUTHOR", "lines": 3, "subsections": [] }, { "name": "COPYRIGHT AND LICENSE", "lines": 4, "subsections": [] }, { "name": "SEE ALSO", "lines": 2, "subsections": [] }, { "name": "BUGS", "lines": 2, "subsections": [] } ], "sections": { "NAME": { "content": "Time::Piece - Object Oriented time objects\n", "subsections": [] }, "SYNOPSIS": { "content": "use Time::Piece;\n\nmy $t = localtime;\nprint \"Time is $t\\n\";\nprint \"Year is \", $t->year, \"\\n\";\n", "subsections": [] }, "DESCRIPTION": { "content": "This module replaces the standard \"localtime\" and \"gmtime\" functions with implementations that\nreturn objects. It does so in a backwards compatible manner, so that using localtime/gmtime in\nthe way documented in perlfunc will still return what you expect.\n\nThe module actually implements most of an interface described by Larry Wall on the perl5-porters\nmailing list here: \n", "subsections": [] }, "USAGE": { "content": "After importing this module, when you use localtime or gmtime in a scalar context, rather than\ngetting an ordinary scalar string representing the date and time, you get a Time::Piece object,\nwhose stringification happens to produce the same effect as the localtime and gmtime functions.\nThere is also a new() constructor provided, which is the same as localtime(), except when passed\na Time::Piece object, in which case it's a copy constructor. The following methods are available\non the object:\n\n$t->sec # also available as $t->second\n$t->min # also available as $t->minute\n$t->hour # 24 hour\n$t->mday # also available as $t->dayofmonth\n$t->mon # 1 = January\n$t->mon # 0 = January\n$t->monname # Feb\n$t->month # same as $t->monname\n$t->fullmonth # February\n$t->year # based at 0 (year 0 AD is, of course 1 BC)\n$t->year # year minus 1900\n$t->yy # 2 digit year\n$t->wday # 1 = Sunday\n$t->wday # 0 = Sunday\n$t->dayofweek # 0 = Sunday\n$t->wdayname # Tue\n$t->day # same as wdayname\n$t->fullday # Tuesday\n$t->yday # also available as $t->dayofyear, 0 = Jan 01\n$t->isdst # also available as $t->daylightsavings\n\n$t->hms # 12:34:56\n$t->hms(\".\") # 12.34.56\n$t->time # same as $t->hms\n\n$t->ymd # 2000-02-29\n$t->date # same as $t->ymd\n$t->mdy # 02-29-2000\n$t->mdy(\"/\") # 02/29/2000\n$t->dmy # 29-02-2000\n$t->dmy(\".\") # 29.02.2000\n$t->datetime # 2000-02-29T12:34:56 (ISO 8601)\n$t->cdate # Tue Feb 29 12:34:56 2000\n\"$t\" # same as $t->cdate\n\n$t->epoch # seconds since the epoch\n$t->tzoffset # timezone offset in a Time::Seconds object\n\n$t->julianday # number of days since Julian period began\n$t->mjd # modified Julian date (JD-2400000.5 days)\n\n$t->week # week number (ISO 8601)\n\n$t->isleapyear # true if it's a leap year\n$t->monthlastday # 28-31\n\n$t->timeseparator($s) # set the default separator (default \":\")\n$t->dateseparator($s) # set the default separator (default \"-\")\n$t->daylist(@days) # set the default weekdays\n$t->monlist(@days) # set the default months\n\n$t->strftime(FORMAT) # same as POSIX::strftime (without the overhead\n# of the full POSIX extension)\n$t->strftime() # \"Tue, 29 Feb 2000 12:34:56 GMT\"\n\nTime::Piece->strptime(STRING, FORMAT)\n# see strptime man page. Creates a new\n# Time::Piece object\n\nNote that \"localtime\" and \"gmtime\" are not listed above. If called as methods on a Time::Piece\nobject, they act as constructors, returning a new Time::Piece object for the current time. In\nother words: they're not useful as methods.\n", "subsections": [ { "name": "Local Locales", "content": "Both wdayname (day) and monname (month) allow passing in a list to use to index the name of the\ndays against. This can be useful if you need to implement some form of localisation without\nactually installing or using locales. Note that this is a global override and will affect all\nTime::Piece instances.\n\nmy @days = qw( Dimanche Lundi Merdi Mercredi Jeudi Vendredi Samedi );\n\nmy $frenchday = localtime->day(@days);\n\nThese settings can be overridden globally too:\n\nTime::Piece::daylist(@days);\n\nOr for months:\n\nTime::Piece::monlist(@months);\n\nAnd locally for months:\n\nprint localtime->month(@months);\n\nOr to populate with your current system locale call: Time::Piece->uselocale();\n" }, { "name": "Date Calculations", "content": "It's possible to use simple addition and subtraction of objects:\n\nuse Time::Seconds;\n\nmy $seconds = $t1 - $t2;\n$t1 += ONEDAY; # add 1 day (constant from Time::Seconds)\n\nThe following are valid ($t1 and $t2 are Time::Piece objects):\n\n$t1 - $t2; # returns Time::Seconds object\n$t1 - 42; # returns Time::Piece object\n$t1 + 533; # returns Time::Piece object\n\nHowever adding a Time::Piece object to another Time::Piece object will cause a runtime error.\n\nNote that the first of the above returns a Time::Seconds object, so while examining the object\nwill print the number of seconds (because of the overloading), you can also get the number of\nminutes, hours, days, weeks and years in that delta, using the Time::Seconds API.\n\nIn addition to adding seconds, there are two APIs for adding months and years:\n\n$t = $t->addmonths(6);\n$t = $t->addyears(5);\n\nThe months and years can be negative for subtractions. Note that there is some \"strange\"\nbehaviour when adding and subtracting months at the ends of months. Generally when the resulting\nmonth is shorter than the starting month then the number of overlap days is added. For example\nsubtracting a month from 2008-03-31 will not result in 2008-02-31 as this is an impossible date.\nInstead you will get 2008-03-02. This appears to be consistent with other date manipulation\ntools.\n" }, { "name": "Truncation", "content": "Calling the \"truncate\" method returns a copy of the object but with the time truncated to the\nstart of the supplied unit.\n\n$t = $t->truncate(to => 'day');\n\nThis example will set the time to midnight on the same date which $t had previously. Allowed\nvalues for the \"to\" parameter are: \"year\", \"quarter\", \"month\", \"day\", \"hour\", \"minute\" and\n\"second\".\n" }, { "name": "Date Comparisons", "content": "Date comparisons are also possible, using the full suite of \"<\", \">\", \"<=\", \">=\", \"<=>\", \"==\"\nand \"!=\".\n" }, { "name": "Date Parsing", "content": "Time::Piece has a built-in strptime() function (from FreeBSD), allowing you incredibly flexible\ndate parsing routines. For example:\n\nmy $t = Time::Piece->strptime(\"Sunday 3rd Nov, 1943\",\n\"%A %drd %b, %Y\");\n\nprint $t->strftime(\"%a, %d %b %Y\");\n\nOutputs:\n\nWed, 03 Nov 1943\n\n(see, it's even smart enough to fix my obvious date bug)\n\nFor more information see \"man strptime\", which should be on all unix systems.\n\nAlternatively look here: \n\nCAVEAT %A, %a, %B, %b, and friends\nTime::Piece::strptime by default can only parse American English date names. Meanwhile,\nTime::Piece->strftime() will return date names that use the current configured system locale.\nThis means dates returned by strftime might not be able to be parsed by strptime. This is the\ndefault behavior and can be overridden by calling Time::Piece->uselocale(). This builds a list\nof the current locale's day and month names which strptime will use to parse with. Note this is\na global override and will affect all Time::Piece instances.\n\nFor instance with a German locale:\n\nlocaltime->daylist();\n\nReturns\n\n( 'Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat' )\n\nWhile:\n\nTime::Piece->uselocale();\nlocaltime->daylist();\n\nReturns\n\n( 'So', 'Mo', 'Di', 'Mi', 'Do', 'Fr', 'Sa' )\n\nYYYY-MM-DDThh:mm:ss\nThe ISO 8601 standard defines the date format to be YYYY-MM-DD, and the time format to be\nhh:mm:ss (24 hour clock), and if combined, they should be concatenated with date first and with\na capital 'T' in front of the time.\n" }, { "name": "Week Number", "content": "The *week number* may be an unknown concept to some readers. The ISO 8601 standard defines that\nweeks begin on a Monday and week 1 of the year is the week that includes both January 4th and\nthe first Thursday of the year. In other words, if the first Monday of January is the 2nd, 3rd,\nor 4th, the preceding days of the January are part of the last week of the preceding year. Week\nnumbers range from 1 to 53.\n" }, { "name": "Global Overriding", "content": "Finally, it's possible to override localtime and gmtime everywhere, by including the ':override'\ntag in the import list:\n\nuse Time::Piece ':override';\n" } ] }, "CAVEATS": { "content": "Setting $ENV{TZ} in Threads on Win32\nNote that when using perl in the default build configuration on Win32 (specifically, when perl\nis built with PERLIMPLICITSYS), each perl interpreter maintains its own copy of the\nenvironment and only the main interpreter will update the process environment seen by strftime.\n\nTherefore, if you make changes to $ENV{TZ} from inside a thread other than the main thread then\nthose changes will not be seen by strftime if you subsequently call that with the %Z formatting\ncode. You must change $ENV{TZ} in the main thread to have the desired effect in this case (and\nyou must also call tzset() in the main thread to register the environment change).\n\nFurthermore, remember that this caveat also applies to fork(), which is emulated by threads on\nWin32.\n", "subsections": [ { "name": "Use of epoch seconds", "content": "This module internally uses the epoch seconds system that is provided via the perl \"time()\"\nfunction and supported by \"gmtime()\" and \"localtime()\".\n\nIf your perl does not support times larger than \"2^31\" seconds then this module is likely to\nfail at processing dates beyond the year 2038. There are moves afoot to fix that in perl.\nAlternatively use 64 bit perl. Or if none of those are options, use the DateTime module which\nhas support for years well into the future and past.\n\nAlso, the internal representation of Time::Piece->strftime deviates from the standard POSIX\nimplementation in that is uses the epoch (instead of separate year, month, day parts). This\nchange was added in version 1.30. If you must have a more traditional strftime (which will\nnormally never calculate day light saving times correctly), you can pass the date parts from\nTime::Piece into the strftime function provided by the POSIX module (see strftime in POSIX ).\n" } ] }, "AUTHOR": { "content": "Matt Sergeant, matt@sergeant.org Jarkko Hietaniemi, jhi@iki.fi (while creating Time::Piece for\ncore perl)\n", "subsections": [] }, "COPYRIGHT AND LICENSE": { "content": "Copyright 2001, Larry Wall.\n\nThis module is free software, you may distribute it under the same terms as Perl.\n", "subsections": [] }, "SEE ALSO": { "content": "The excellent Calendar FAQ at \n", "subsections": [] }, "BUGS": { "content": "The test harness leaves much to be desired. Patches welcome.\n", "subsections": [] } } } }