1DateTime::Format::StrptUismeer(3C)ontributed Perl DocumeDnattaetTiiomne::Format::Strptime(3)
2
3
4
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
15 my $strp = DateTime::Format::Strptime->new(
16 pattern => '%T',
17 locale => 'en_AU',
18 time_zone => 'Australia/Melbourne',
19 );
20
21 my $dt = $strp->parse_datetime('23:16:42');
22
23 $strp->format_datetime($dt);
24
25 # 23:16:42
26
27 # 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
35 # 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
52 DateTime::Format::Strptime->new(%args)
53 This methods creates a new object. It accepts the following arguments:
54
55 • pattern
56
57 This is the pattern to use for parsing. This is required.
58
59 • strict
60
61 This is a boolean which disables or enables strict matching mode.
62
63 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
69 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
75 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
79 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
83 • time_zone
84
85 The default time zone to use for objects returned from parsing.
86
87 • zone_map
88
89 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
94 zone_map => { PST => '-0800', EST => '-0600' }
95
96 Note that you can also override non-ambiguous mappings if you want
97 to as well.
98
99 • locale
100
101 The locale to use for objects returned from parsing.
102
103 • on_error
104
105 This can be one of 'undef' (the string, not an "undef"), 'croak',
106 or a subroutine reference.
107
108 • 'undef'
109
110 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
116 • 'croak'
117
118 The module will croak with an error message on errors.
119
120 • sub{...} or \&subname
121
122 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
126 If your sub does not die, then the formatter will continue
127 on as if "on_error" was 'undef'.
128
129 $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
133 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
137 $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
142 $strptime->locale
143 This method returns the locale passed to the object's constructor.
144
145 $strptime->pattern
146 This method returns the pattern passed to the object's constructor.
147
148 $strptime->time_zone
149 This method returns the time zone passed to the object's constructor.
150
151 $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
159 strptime( $strptime_pattern, $string )
160 Given a pattern and a string this function will return a new "DateTime"
161 object.
162
163 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
171 • %%
172
173 The % character.
174
175 • %a or %A
176
177 The weekday name according to the given locale, in abbreviated form
178 or the full name.
179
180 • %b or %B or %h
181
182 The month name according to the given locale, in abbreviated form
183 or the full name.
184
185 • %c
186
187 The datetime format according to the given locale.
188
189 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
195 • %C
196
197 The century number (0-99).
198
199 • %d or %e
200
201 The day of month (01-31). This will parse single digit numbers as
202 well.
203
204 • %D
205
206 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
210 • %F
211
212 Equivalent to %Y-%m-%d. (This is the ISO style date)
213
214 • %g
215
216 The year corresponding to the ISO week number, but without the
217 century (0-99).
218
219 • %G
220
221 The 4-digit year corresponding to the ISO week number.
222
223 • %H
224
225 The hour (00-23). This will parse single digit numbers as well.
226
227 • %I
228
229 The hour on a 12-hour clock (1-12).
230
231 • %j
232
233 The day number in the year (1-366).
234
235 • %m
236
237 The month number (01-12). This will parse single digit numbers as
238 well.
239
240 • %M
241
242 The minute (00-59). This will parse single digit numbers as well.
243
244 • %n
245
246 Arbitrary whitespace.
247
248 • %N
249
250 Nanoseconds. For other sub-second values use "%[number]N".
251
252 • %p or %P
253
254 The equivalent of AM or PM according to the locale in use. See
255 DateTime::Locale.
256
257 • %r
258
259 Equivalent to %I:%M:%S %p.
260
261 • %R
262
263 Equivalent to %H:%M.
264
265 • %s
266
267 Number of seconds since the Epoch.
268
269 • %S
270
271 The second (0-60; 60 may occur for leap seconds. See
272 DateTime::LeapSecond).
273
274 • %t
275
276 Arbitrary whitespace.
277
278 • %T
279
280 Equivalent to %H:%M:%S.
281
282 • %U
283
284 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
287 • %u
288
289 The weekday number (1-7) with Monday = 1. This is the "DateTime"
290 standard.
291
292 • %w
293
294 The weekday number (0-6) with Sunday = 0.
295
296 • %W
297
298 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
301 • %x
302
303 The date format according to the given locale.
304
305 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
311 • %X
312
313 The time format according to the given locale.
314
315 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
321 • %y
322
323 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
328 • %Y
329
330 A 4-digit year, including century (for example, 1991).
331
332 • %z
333
334 An RFC-822/ISO 8601 standard time zone specification. (For example
335 +1100) [See note below]
336
337 • %Z
338
339 The timezone name. (For example EST -- which is ambiguous) [See
340 note below]
341
342 • %O
343
344 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
355 http://datetime.perl.org/
356
357 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
365 Bugs may be submitted at
366 <https://github.com/houseabsolute/DateTime-Format-Strptime/issues>.
367
368 There is a mailing list available for users of this distribution,
369 <mailto:datetime@perl.org>.
370
371 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
383 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
387 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
392 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
398 • Rick Measham <rickm@cpan.org>
399
401 • Christian Hansen <chansen@cpan.org>
402
403 • D. Ilmari Mannsåker <ilmari.mannsaker@net-a-porter.com>
404
405 • gregor herrmann <gregoa@debian.org>
406
407 • key-amb <yasutake.kiyoshi@gmail.com>
408
409 • Mohammad S Anwar <mohammad.anwar@yahoo.com>
410
412 This software is Copyright (c) 2015 - 2021 by Dave Rolsky.
413
414 This is free software, licensed under:
415
416 The Artistic License 2.0 (GPL Compatible)
417
418 The full text of the license can be found in the LICENSE file included
419 with this distribution.
420
421
422
423perl v5.36.0 2023-01-20 DateTime::Format::Strptime(3)