README.md
1# NAME
2
3DateTime::Format::Strptime - Parse and format strp and strf time patterns
4
5# VERSION
6
7version 1.79
8
9# SYNOPSIS
10
11 use DateTime::Format::Strptime;
12
13 my $strp = DateTime::Format::Strptime->new(
14 pattern => '%T',
15 locale => 'en_AU',
16 time_zone => 'Australia/Melbourne',
17 );
18
19 my $dt = $strp->parse_datetime('23:16:42');
20
21 $strp->format_datetime($dt);
22
23 # 23:16:42
24
25 # Croak when things go wrong:
26 my $strp = DateTime::Format::Strptime->new(
27 pattern => '%T',
28 locale => 'en_AU',
29 time_zone => 'Australia/Melbourne',
30 on_error => 'croak',
31 );
32
33 # Do something else when things go wrong:
34 my $strp = DateTime::Format::Strptime->new(
35 pattern => '%T',
36 locale => 'en_AU',
37 time_zone => 'Australia/Melbourne',
38 on_error => \&phone_police,
39 );
40
41# DESCRIPTION
42
43This module implements most of `strptime(3)`, the POSIX function that is the
44reverse of `strftime(3)`, for `DateTime`. While `strftime` takes a
45`DateTime` and a pattern and returns a string, `strptime` takes a string and
46a pattern and returns the `DateTime` object associated.
47
48# METHODS
49
50This class offers the following methods.
51
52## DateTime::Format::Strptime->new(%args)
53
54This methods creates a new object. It accepts the following arguments:
55
56- pattern
57
58 This is the pattern to use for parsing. This is required.
59
60- strict
61
62 This is a boolean which disables or enables strict matching mode.
63
64 By default, this module turns your pattern into a regex that will match
65 anywhere in a string. So given the pattern `%Y%m%d%H%M%S` it will match a
66 string like `20161214233712`. However, this also means that a this pattern
67 will match **any** string that contains 14 or more numbers! This behavior can be
68 very surprising.
69
70 If you enable strict mode, then the generated regex is wrapped in boundary
71 checks of the form `/(?:\A|\b)...(?:\b|\z_/)`. These checks ensure that the
72 pattern will only match when at the beginning or end of a string, or when it is
73 separated by other text with a word boundary (`\w` versus `\W`).
74
75 By default, strict mode is off. This is done for backwards compatibility.
76 Future releases may turn it on by default, as it produces less surprising
77 behavior in many cases.
78
79 Because the default may change in the future, **you are strongly encouraged
80 to explicitly set this when constructing all `DateTime::Format::Strptime`
81 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 default,
90 the parser will die when it parses an ambiguous abbreviation. You may specify a
91 `zone_map` parameter as a hashref to map zone abbreviations however you like:
92
93 zone_map => { PST => '-0800', EST => '-0600' }
94
95 Note that you can also override non-ambiguous mappings if you want to as well.
96
97- locale
98
99 The locale to use for objects returned from parsing.
100
101- on\_error
102
103 This can be one of `'undef'` (the string, not an `undef`), 'croak', or a
104 subroutine reference.
105
106 - 'undef'
107
108 This is the default behavior. The module will return `undef` on errors. The
109 error can be accessed using the `$object->errmsg` method. This is the
110 ideal behaviour for interactive use where a user might provide an illegal
111 pattern or a date that doesn't match the pattern.
112
113 - 'croak'
114
115 The module will croak with an error message on errors.
116
117 - sub{...} or \\&subname
118
119 When given a code ref, the module will call that sub on errors. The sub
120 receives two parameters: the object and the error message.
121
122 If your sub does not die, then the formatter will continue on as if `on_error`
123 was `'undef'`.
124
125## $strptime->parse\_datetime($string)
126
127Given a string in the pattern specified in the constructor, this method will
128return a new `DateTime` object.
129
130If given a string that doesn't match the pattern, the formatter will croak or
131return undef, depending on the setting of `on_error` in the constructor.
132
133## $strptime->format\_datetime($datetime)
134
135Given a `DateTime` object, this methods returns a string formatted in the
136object's format. This method is synonymous with `DateTime`'s strftime method.
137
138## $strptime->locale
139
140This method returns the locale passed to the object's constructor.
141
142## $strptime->pattern
143
144This method returns the pattern passed to the object's constructor.
145
146## $strptime->time\_zone
147
148This method returns the time zone passed to the object's constructor.
149
150## $strptime->errmsg
151
152If the on\_error behavior of the object is 'undef', you can retrieve error
153messages with this method so you can work out why things went wrong.
154
155# EXPORTS
156
157These subs are available as optional exports.
158
159## strptime( $strptime\_pattern, $string )
160
161Given a pattern and a string this function will return a new `DateTime`
162object.
163
164## strftime( $strftime\_pattern, $datetime )
165
166Given a pattern and a `DateTime` object this function will return a formatted
167string.
168
169# STRPTIME PATTERN TOKENS
170
171The following tokens are allowed in the pattern string for strptime
172(parse\_datetime):
173
174- %%
175
176 The % character.
177
178- %a or %A
179
180 The weekday name according to the given locale, in abbreviated form or the full
181 name.
182
183- %b or %B or %h
184
185 The month name according to the given locale, in abbreviated form or the full
186 name.
187
188- %c
189
190 The datetime format according to the given locale.
191
192 Note that this format can change without warning in new versions of
193 [DateTime::Locale](https://metacpan.org/pod/DateTime%3A%3ALocale). You should not use this pattern unless the string you are
194 parsing was generated by using this pattern with [DateTime](https://metacpan.org/pod/DateTime) **and** you are
195 sure that this string was generated with the same version of
196 [DateTime::Locale](https://metacpan.org/pod/DateTime%3A%3ALocale) that the parser is using.
197
198- %C
199
200 The century number (0-99).
201
202- %d or %e
203
204 The day of month (01-31). This will parse single digit numbers as well.
205
206- %D
207
208 Equivalent to %m/%d/%y. (This is the American style date, very confusing to
209 non-Americans, especially since %d/%m/%y is widely used in Europe. The ISO 8601
210 standard pattern is %F.)
211
212- %F
213
214 Equivalent to %Y-%m-%d. (This is the ISO style date)
215
216- %g
217
218 The year corresponding to the ISO week number, but without the century (0-99).
219
220- %G
221
222 The 4-digit year corresponding to the ISO week number.
223
224- %H
225
226 The hour (00-23). This will parse single digit numbers as well.
227
228- %I
229
230 The hour on a 12-hour clock (1-12).
231
232- %j
233
234 The day number in the year (1-366).
235
236- %m
237
238 The month number (01-12). This will parse single digit numbers as 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](https://metacpan.org/pod/DateTime%3A%3ALocale).
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 [DateTime::LeapSecond](https://metacpan.org/pod/DateTime%3A%3ALeapSecond)).
272
273- %t
274
275 Arbitrary whitespace.
276
277- %T
278
279 Equivalent to %H:%M:%S.
280
281- %U
282
283 The week number with Sunday the first day of the week (0-53). The first Sunday
284 of January is the first day of week 1.
285
286- %u
287
288 The weekday number (1-7) with Monday = 1. This is the `DateTime` standard.
289
290- %w
291
292 The weekday number (0-6) with Sunday = 0.
293
294- %W
295
296 The week number with Monday the first day of the week (0-53). The first Monday
297 of January is the first day of week 1.
298
299- %x
300
301 The date format according to the given locale.
302
303 Note that this format can change without warning in new versions of
304 [DateTime::Locale](https://metacpan.org/pod/DateTime%3A%3ALocale). You should not use this pattern unless the string you are
305 parsing was generated by using this pattern with [DateTime](https://metacpan.org/pod/DateTime) **and** you are
306 sure that this string was generated with the same version of
307 [DateTime::Locale](https://metacpan.org/pod/DateTime%3A%3ALocale) that the parser is using.
308
309- %X
310
311 The time format according to the given locale.
312
313 Note that this format can change without warning in new versions of
314 [DateTime::Locale](https://metacpan.org/pod/DateTime%3A%3ALocale). You should not use this pattern unless the string you are
315 parsing was generated by using this pattern with [DateTime](https://metacpan.org/pod/DateTime) **and** you are
316 sure that this string was generated with the same version of
317 [DateTime::Locale](https://metacpan.org/pod/DateTime%3A%3ALocale) that the parser is using.
318
319- %y
320
321 The year within century (0-99). When a century is not otherwise specified (with
322 a value for %C), values in the range 69-99 refer to years in the twentieth
323 century (1969-1999); values in the range 00-68 refer to years in the
324 twenty-first century (2000-2068).
325
326- %Y
327
328 A 4-digit year, including century (for example, 1991).
329
330- %z
331
332 An RFC-822/ISO 8601 standard time zone specification. (For example +1100) \[See
333 note below\]
334
335- %Z
336
337 The timezone name. (For example EST -- which is ambiguous) \[See note below\]
338
339- %O
340
341 This extended token allows the use of Olson Time Zone names to appear in parsed
342 strings. **NOTE**: This pattern cannot be passed to `DateTime`'s `strftime()`
343 method, but can be passed to `format_datetime()`.
344
345# AUTHOR EMERITUS
346
347This module was created by Rick Measham.
348
349# SEE ALSO
350
351`datetime@perl.org` mailing list.
352
353http://datetime.perl.org/
354
355[perl](https://metacpan.org/pod/perl), [DateTime](https://metacpan.org/pod/DateTime), [DateTime::TimeZone](https://metacpan.org/pod/DateTime%3A%3ATimeZone), [DateTime::Locale](https://metacpan.org/pod/DateTime%3A%3ALocale)
356
357# BUGS
358
359Please report any bugs or feature requests to
360`bug-datetime-format-strptime@rt.cpan.org`, or through the web interface at
361[http://rt.cpan.org](http://rt.cpan.org). I will be notified, and then you'll automatically be
362notified of progress on your bug as I make changes.
363
364Bugs may be submitted at [https://github.com/houseabsolute/DateTime-Format-Strptime/issues](https://github.com/houseabsolute/DateTime-Format-Strptime/issues).
365
366There is a mailing list available for users of this distribution,
367[mailto:datetime@perl.org](mailto:datetime@perl.org).
368
369I am also usually active on IRC as 'autarch' on `irc://irc.perl.org`.
370
371# SOURCE
372
373The source code repository for DateTime-Format-Strptime can be found at [https://github.com/houseabsolute/DateTime-Format-Strptime](https://github.com/houseabsolute/DateTime-Format-Strptime).
374
375# DONATIONS
376
377If you'd like to thank me for the work I've done on this module, please
378consider making a "donation" to me via PayPal. I spend a lot of free time
379creating free software, and would appreciate any support you'd care to offer.
380
381Please note that **I am not suggesting that you must do this** in order for me
382to continue working on this particular software. I will continue to do so,
383inasmuch as I have in the past, for as long as it interests me.
384
385Similarly, a donation made in this way will probably not make me work on this
386software much more, unless I get so many donations that I can consider working
387on free software full time (let's all have a chuckle at that together).
388
389To donate, log into PayPal and send money to autarch@urth.org, or use the
390button at [https://www.urth.org/fs-donation.html](https://www.urth.org/fs-donation.html).
391
392# AUTHORS
393
394- Dave Rolsky <autarch@urth.org>
395- Rick Measham <rickm@cpan.org>
396
397# CONTRIBUTORS
398
399- Christian Hansen <chansen@cpan.org>
400- D. Ilmari Mannsåker <ilmari.mannsaker@net-a-porter.com>
401- gregor herrmann <gregoa@debian.org>
402- key-amb <yasutake.kiyoshi@gmail.com>
403- Mohammad S Anwar <mohammad.anwar@yahoo.com>
404
405# COPYRIGHT AND LICENSE
406
407This software is Copyright (c) 2015 - 2021 by Dave Rolsky.
408
409This is free software, licensed under:
410
411 The Artistic License 2.0 (GPL Compatible)
412
413The full text of the license can be found in the
414`LICENSE` file included with this distribution.
415