1DateTime::Format::StrptUismeer(3C)ontributed Perl DocumeDnattaetTiiomne::Format::Strptime(3)
2
3
4

NAME

6       DateTime::Format::Strptime - Parse and format strp and strf time
7       patterns
8

VERSION

10       version 1.79
11

SYNOPSIS

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

DESCRIPTION

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

METHODS

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

EXPORTS

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

STRPTIME PATTERN TOKENS

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

AUTHOR EMERITUS

350       This module was created by Rick Measham.
351

SEE ALSO

353       "datetime@perl.org" mailing list.
354
355       http://datetime.perl.org/
356
357       perl, DateTime, DateTime::TimeZone, DateTime::Locale
358

BUGS

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

SOURCE

374       The source code repository for DateTime-Format-Strptime can be found at
375       <https://github.com/houseabsolute/DateTime-Format-Strptime>.
376

DONATIONS

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

AUTHORS

396       •   Dave Rolsky <autarch@urth.org>
397
398       •   Rick Measham <rickm@cpan.org>
399

CONTRIBUTORS

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.38.0                      2023-07-20     DateTime::Format::Strptime(3)
Impressum