1DateTime::Format::StrptUismeer(3C)ontributed Perl DocumeDnattaetTiiomne::Format::Strptime(3)
2
6 DateTime::Format::Strptime - Parse and format strp and strf time
7 patterns
8
10 version 1.79
11
13 use DateTime::Format::Strptime;
14 my $strp = DateTime::Format::Strptime->new(
16 pattern => '%T',
17 locale => 'en_AU',
18 time_zone => 'Australia/Melbourne',
19 );
20 my $dt = $strp->parse_datetime('23:16:42');
22 $strp->format_datetime($dt);
24 # 23:16:42
26 # Croak when things go wrong:
28 my $strp = DateTime::Format::Strptime->new(
29 pattern => '%T',
30 locale => 'en_AU',
31 time_zone => 'Australia/Melbourne',
32 on_error => 'croak',
33 );
34 # Do something else when things go wrong:
36 my $strp = DateTime::Format::Strptime->new(
37 pattern => '%T',
38 locale => 'en_AU',
39 time_zone => 'Australia/Melbourne',
40 on_error => \&phone_police,
41 );
42
44 This module implements most of strptime(3), the POSIX function that is
45 the reverse of strftime(3), for "DateTime". While "strftime" takes a
46 "DateTime" and a pattern and returns a string, "strptime" takes a
47 string and a pattern and returns the "DateTime" object associated.
48
50 This class offers the following methods.
51 DateTime::Format::Strptime->new(%args)
53 This methods creates a new object. It accepts the following arguments:
54 • pattern
56 This is the pattern to use for parsing. This is required.
58 • strict
60 This is a boolean which disables or enables strict matching mode.
62 By default, this module turns your pattern into a regex that will
64 match anywhere in a string. So given the pattern "%Y%m%d%H%M%S" it
65 will match a string like 20161214233712. However, this also means
66 that a this pattern will match any string that contains 14 or more
67 numbers! This behavior can be very surprising.
68 If you enable strict mode, then the generated regex is wrapped in
70 boundary checks of the form "/(?:\A|\b)...(?:\b|\z_/)". These
71 checks ensure that the pattern will only match when at the
72 beginning or end of a string, or when it is separated by other text
73 with a word boundary ("\w" versus "\W").
74 By default, strict mode is off. This is done for backwards
76 compatibility. Future releases may turn it on by default, as it
77 produces less surprising behavior in many cases.
78 Because the default may change in the future, you are strongly
80 encouraged to explicitly set this when constructing all
81 "DateTime::Format::Strptime" objects.
82 • time_zone
84 The default time zone to use for objects returned from parsing.
86 • zone_map
88 Some time zone abbreviations are ambiguous (e.g. PST, EST, EDT). By
90 default, the parser will die when it parses an ambiguous
91 abbreviation. You may specify a "zone_map" parameter as a hashref
92 to map zone abbreviations however you like:
93 zone_map => { PST => '-0800', EST => '-0600' }
95 Note that you can also override non-ambiguous mappings if you want
97 to as well.
98 • locale
100 The locale to use for objects returned from parsing.
102 • on_error
104 This can be one of 'undef' (the string, not an "undef"), 'croak',
106 or a subroutine reference.
107 • 'undef'
109 This is the default behavior. The module will return
111 "undef" on errors. The error can be accessed using the
112 "$object->errmsg" method. This is the ideal behaviour for
113 interactive use where a user might provide an illegal
114 pattern or a date that doesn't match the pattern.
115 • 'croak'
117 The module will croak with an error message on errors.
119 • sub{...} or \&subname
121 When given a code ref, the module will call that sub on
123 errors. The sub receives two parameters: the object and the
124 error message.
125 If your sub does not die, then the formatter will continue
127 on as if "on_error" was 'undef'.
128 $strptime->parse_datetime($string)
130 Given a string in the pattern specified in the constructor, this method
131 will return a new "DateTime" object.
132 If given a string that doesn't match the pattern, the formatter will
134 croak or return undef, depending on the setting of "on_error" in the
135 constructor.
136 $strptime->format_datetime($datetime)
138 Given a "DateTime" object, this methods returns a string formatted in
139 the object's format. This method is synonymous with "DateTime"'s
140 strftime method.
141 $strptime->locale
143 This method returns the locale passed to the object's constructor.
144 $strptime->pattern
146 This method returns the pattern passed to the object's constructor.
147 $strptime->time_zone
149 This method returns the time zone passed to the object's constructor.
150 $strptime->errmsg
152 If the on_error behavior of the object is 'undef', you can retrieve
153 error messages with this method so you can work out why things went
154 wrong.
155
157 These subs are available as optional exports.
158 strptime( $strptime_pattern, $string )
160 Given a pattern and a string this function will return a new "DateTime"
161 object.
162 strftime( $strftime_pattern, $datetime )
164 Given a pattern and a "DateTime" object this function will return a
165 formatted string.
166
168 The following tokens are allowed in the pattern string for strptime
169 (parse_datetime):
170 • %%
172 The % character.
174 • %a or %A
176 The weekday name according to the given locale, in abbreviated form
178 or the full name.
179 • %b or %B or %h
181 The month name according to the given locale, in abbreviated form
183 or the full name.
184 • %c
186 The datetime format according to the given locale.
188 Note that this format can change without warning in new versions of
190 DateTime::Locale. You should not use this pattern unless the string
191 you are parsing was generated by using this pattern with DateTime
192 and you are sure that this string was generated with the same
193 version of DateTime::Locale that the parser is using.
194 • %C
196 The century number (0-99).
198 • %d or %e
200 The day of month (01-31). This will parse single digit numbers as
202 well.
203 • %D
205 Equivalent to %m/%d/%y. (This is the American style date, very
207 confusing to non-Americans, especially since %d/%m/%y is widely
208 used in Europe. The ISO 8601 standard pattern is %F.)
209 • %F
211 Equivalent to %Y-%m-%d. (This is the ISO style date)
213 • %g
215 The year corresponding to the ISO week number, but without the
217 century (0-99).
218 • %G
220 The 4-digit year corresponding to the ISO week number.
222 • %H
224 The hour (00-23). This will parse single digit numbers as well.
226 • %I
228 The hour on a 12-hour clock (1-12).
230 • %j
232 The day number in the year (1-366).
234 • %m
236 The month number (01-12). This will parse single digit numbers as
238 well.
239 • %M
241 The minute (00-59). This will parse single digit numbers as well.
243 • %n
245 Arbitrary whitespace.
247 • %N
249 Nanoseconds. For other sub-second values use "%[number]N".
251 • %p or %P
253 The equivalent of AM or PM according to the locale in use. See
255 DateTime::Locale.
256 • %r
258 Equivalent to %I:%M:%S %p.
260 • %R
262 Equivalent to %H:%M.
264 • %s
266 Number of seconds since the Epoch.
268 • %S
270 The second (0-60; 60 may occur for leap seconds. See
272 DateTime::LeapSecond).
273 • %t
275 Arbitrary whitespace.
277 • %T
279 Equivalent to %H:%M:%S.
281 • %U
283 The week number with Sunday the first day of the week (0-53). The
285 first Sunday of January is the first day of week 1.
286 • %u
288 The weekday number (1-7) with Monday = 1. This is the "DateTime"
290 standard.
291 • %w
293 The weekday number (0-6) with Sunday = 0.
295 • %W
297 The week number with Monday the first day of the week (0-53). The
299 first Monday of January is the first day of week 1.
300 • %x
302 The date format according to the given locale.
304 Note that this format can change without warning in new versions of
306 DateTime::Locale. You should not use this pattern unless the string
307 you are parsing was generated by using this pattern with DateTime
308 and you are sure that this string was generated with the same
309 version of DateTime::Locale that the parser is using.
310 • %X
312 The time format according to the given locale.
314 Note that this format can change without warning in new versions of
316 DateTime::Locale. You should not use this pattern unless the string
317 you are parsing was generated by using this pattern with DateTime
318 and you are sure that this string was generated with the same
319 version of DateTime::Locale that the parser is using.
320 • %y
322 The year within century (0-99). When a century is not otherwise
324 specified (with a value for %C), values in the range 69-99 refer to
325 years in the twentieth century (1969-1999); values in the range
326 00-68 refer to years in the twenty-first century (2000-2068).
327 • %Y
329 A 4-digit year, including century (for example, 1991).
331 • %z
333 An RFC-822/ISO 8601 standard time zone specification. (For example
335 +1100) [See note below]
336 • %Z
338 The timezone name. (For example EST -- which is ambiguous) [See
340 note below]
341 • %O
343 This extended token allows the use of Olson Time Zone names to
345 appear in parsed strings. NOTE: This pattern cannot be passed to
346 "DateTime"'s strftime() method, but can be passed to
347 format_datetime().
348
350 This module was created by Rick Measham.
351
353 "datetime@perl.org" mailing list.
354 http://datetime.perl.org/
356 perl, DateTime, DateTime::TimeZone, DateTime::Locale
358
360 Please report any bugs or feature requests to
361 "bug-datetime-format-strptime@rt.cpan.org", or through the web
362 interface at <http://rt.cpan.org>. I will be notified, and then you'll
363 automatically be notified of progress on your bug as I make changes.
364 Bugs may be submitted at
366 <https://github.com/houseabsolute/DateTime-Format-Strptime/issues>.
367 There is a mailing list available for users of this distribution,
369 <mailto:datetime@perl.org>.
370 I am also usually active on IRC as 'autarch' on "irc://irc.perl.org".
372
374 The source code repository for DateTime-Format-Strptime can be found at
375 <https://github.com/houseabsolute/DateTime-Format-Strptime>.
376
378 If you'd like to thank me for the work I've done on this module, please
379 consider making a "donation" to me via PayPal. I spend a lot of free
380 time creating free software, and would appreciate any support you'd
381 care to offer.
382 Please note that I am not suggesting that you must do this in order for
384 me to continue working on this particular software. I will continue to
385 do so, inasmuch as I have in the past, for as long as it interests me.
386 Similarly, a donation made in this way will probably not make me work
388 on this software much more, unless I get so many donations that I can
389 consider working on free software full time (let's all have a chuckle
390 at that together).
391 To donate, log into PayPal and send money to autarch@urth.org, or use
393 the button at <https://www.urth.org/fs-donation.html>.
394
396 • Dave Rolsky <autarch@urth.org>
397 • Rick Measham <rickm@cpan.org>
399
401 • Christian Hansen <chansen@cpan.org>
402 • D. Ilmari Mannsåker <ilmari.mannsaker@net-a-porter.com>
404 • gregor herrmann <gregoa@debian.org>
406 • key-amb <yasutake.kiyoshi@gmail.com>
408 • Mohammad S Anwar <mohammad.anwar@yahoo.com>
410
412 This software is Copyright (c) 2015 - 2021 by Dave Rolsky.
413 This is free software, licensed under:
415 The Artistic License 2.0 (GPL Compatible)
417 The full text of the license can be found in the LICENSE file included
419 with this distribution.
420perl v5.36.0 2023-01-20 DateTime::Format::Strptime(3)