DateTime::Format::Strptime(3pm)

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.76
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       ·   %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

AUTHOR EMERITUS

332       This module was created by Rick Measham.
333

BUGS

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

SOURCE

356       The source code repository for DateTime-Format-Strptime can be found at
357       <https://github.com/houseabsolute/DateTime-Format-Strptime>.
358

DONATIONS

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

AUTHORS

378       ·   Dave Rolsky <autarch@urth.org>
379
380       ·   Rick Measham <rickm@cpan.org>
381

CONTRIBUTORS

383       ·   Christian Hansen <chansen@cpan.org>
384
385       ·   D. Ilmari Mannsåker <ilmari.mannsaker@net-a-porter.com>
386
387       ·   key-amb <yasutake.kiyoshi@gmail.com>
388
389       ·   Mohammad S Anwar <mohammad.anwar@yahoo.com>
390

COPYRIGHT AND LICENSE

392       This software is Copyright (c) 2015 - 2019 by Dave Rolsky.
393
394       This is free software, licensed under:
395
396         The Artistic License 2.0 (GPL Compatible)
397
398       The full text of the license can be found in the LICENSE file included
399       with this distribution.
400
401
402
403perl v5.30.0                      2019-07-26     DateTime::Format::Strptime(3)