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.77
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 · %C
190
191 The century number (0-99).
192
193 · %d or %e
194
195 The day of month (01-31). This will parse single digit numbers as
196 well.
197
198 · %D
199
200 Equivalent to %m/%d/%y. (This is the American style date, very
201 confusing to non-Americans, especially since %d/%m/%y is widely
202 used in Europe. The ISO 8601 standard pattern is %F.)
203
204 · %F
205
206 Equivalent to %Y-%m-%d. (This is the ISO style date)
207
208 · %g
209
210 The year corresponding to the ISO week number, but without the
211 century (0-99).
212
213 · %G
214
215 The 4-digit year corresponding to the ISO week number.
216
217 · %H
218
219 The hour (00-23). This will parse single digit numbers as well.
220
221 · %I
222
223 The hour on a 12-hour clock (1-12).
224
225 · %j
226
227 The day number in the year (1-366).
228
229 · %m
230
231 The month number (01-12). This will parse single digit numbers as
232 well.
233
234 · %M
235
236 The minute (00-59). This will parse single digit numbers as well.
237
238 · %n
239
240 Arbitrary whitespace.
241
242 · %N
243
244 Nanoseconds. For other sub-second values use "%[number]N".
245
246 · %p or %P
247
248 The equivalent of AM or PM according to the locale in use. See
249 DateTime::Locale.
250
251 · %r
252
253 Equivalent to %I:%M:%S %p.
254
255 · %R
256
257 Equivalent to %H:%M.
258
259 · %s
260
261 Number of seconds since the Epoch.
262
263 · %S
264
265 The second (0-60; 60 may occur for leap seconds. See
266 DateTime::LeapSecond).
267
268 · %t
269
270 Arbitrary whitespace.
271
272 · %T
273
274 Equivalent to %H:%M:%S.
275
276 · %U
277
278 The week number with Sunday the first day of the week (0-53). The
279 first Sunday of January is the first day of week 1.
280
281 · %u
282
283 The weekday number (1-7) with Monday = 1. This is the "DateTime"
284 standard.
285
286 · %w
287
288 The weekday number (0-6) with Sunday = 0.
289
290 · %W
291
292 The week number with Monday the first day of the week (0-53). The
293 first Monday of January is the first day of week 1.
294
295 · %x
296
297 The date format according to the given locale.
298
299 · %X
300
301 The time format according to the given locale.
302
303 · %y
304
305 The year within century (0-99). When a century is not otherwise
306 specified (with a value for %C), values in the range 69-99 refer to
307 years in the twentieth century (1969-1999); values in the range
308 00-68 refer to years in the twenty-first century (2000-2068).
309
310 · %Y
311
312 A 4-digit year, including century (for example, 1991).
313
314 · %z
315
316 An RFC-822/ISO 8601 standard time zone specification. (For example
317 +1100) [See note below]
318
319 · %Z
320
321 The timezone name. (For example EST -- which is ambiguous) [See
322 note below]
323
324 · %O
325
326 This extended token allows the use of Olson Time Zone names to
327 appear in parsed strings. NOTE: This pattern cannot be passed to
328 "DateTime"'s "strftime()" method, but can be passed to
329 "format_datetime()".
330
332 This module was created by Rick Measham.
333
335 "datetime@perl.org" mailing list.
336
337 http://datetime.perl.org/
338
339 perl, DateTime, DateTime::TimeZone, DateTime::Locale
340
342 Please report any bugs or feature requests to
343 "bug-datetime-format-strptime@rt.cpan.org", or through the web
344 interface at <http://rt.cpan.org>. I will be notified, and then you'll
345 automatically be notified of progress on your bug as I make changes.
346
347 Bugs may be submitted at
348 <https://github.com/houseabsolute/DateTime-Format-Strptime/issues>.
349
350 There is a mailing list available for users of this distribution,
351 <mailto:datetime@perl.org>.
352
353 I am also usually active on IRC as 'autarch' on "irc://irc.perl.org".
354
356 The source code repository for DateTime-Format-Strptime can be found at
357 <https://github.com/houseabsolute/DateTime-Format-Strptime>.
358
360 If you'd like to thank me for the work I've done on this module, please
361 consider making a "donation" to me via PayPal. I spend a lot of free
362 time creating free software, and would appreciate any support you'd
363 care to offer.
364
365 Please note that I am not suggesting that you must do this in order for
366 me to continue working on this particular software. I will continue to
367 do so, inasmuch as I have in the past, for as long as it interests me.
368
369 Similarly, a donation made in this way will probably not make me work
370 on this software much more, unless I get so many donations that I can
371 consider working on free software full time (let's all have a chuckle
372 at that together).
373
374 To donate, log into PayPal and send money to autarch@urth.org, or use
375 the button at <http://www.urth.org/~autarch/fs-donation.html>.
376
378 · Dave Rolsky <autarch@urth.org>
379
380 · Rick Measham <rickm@cpan.org>
381
383 · Christian Hansen <chansen@cpan.org>
384
385 · D. Ilmari Mannsåker <ilmari.mannsaker@net-a-porter.com>
386
387 · gregor herrmann <gregoa@debian.org>
388
389 · key-amb <yasutake.kiyoshi@gmail.com>
390
391 · Mohammad S Anwar <mohammad.anwar@yahoo.com>
392
394 This software is Copyright (c) 2015 - 2020 by Dave Rolsky.
395
396 This is free software, licensed under:
397
398 The Artistic License 2.0 (GPL Compatible)
399
400 The full text of the license can be found in the LICENSE file included
401 with this distribution.
402
403
404
405perl v5.32.0 2020-07-28 DateTime::Format::Strptime(3)