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

SYNOPSIS

10         use DateTime::Format::Strptime;
11
12         my $Strp = new DateTime::Format::Strptime(
13                                       pattern     => '%T',
14                                       locale      => 'en_AU',
15                                       time_zone   => 'Australia/Melbourne',
16                               );
17
18         my $dt = $Strp->parse_datetime('23:16:42');
19
20         $Strp->format_datetime($dt);
21               # 23:16:42
22
23
24
25         # Croak when things go wrong:
26         my $Strp = new DateTime::Format::Strptime(
27                                       pattern         => '%T',
28                                       locale      => 'en_AU',
29                                       time_zone       => 'Australia/Melbourne',
30                                       on_error        => 'croak',
31                               );
32
33         $newpattern = $Strp->pattern('%Q');
34         # Unidentified token in pattern: %Q in %Q at line 34 of script.pl
35
36         # Do something else when things go wrong:
37         my $Strp = new DateTime::Format::Strptime(
38                                       pattern         => '%T',
39                                       locale      => 'en_AU',
40                                       time_zone       => 'Australia/Melbourne',
41                                       on_error        => \&phone_police,
42                               );
43

DESCRIPTION

45       This module implements most of strptime(3), the POSIX function that is
46       the reverse of strftime(3), for "DateTime". While "strftime" takes a
47       "DateTime" and a pattern and returns a string, "strptime" takes a
48       string and a pattern and returns the "DateTime" object associated.
49

CONSTRUCTOR

51       ·   new( pattern=>$strptime_pattern )
52
53           Creates the format object. You must specify a pattern, you can also
54           specify a "time_zone" and a "locale". If you specify a time zone
55           then any resulting "DateTime" object will be in that time zone. If
56           you do not specify a "time_zone" parameter, but there is a time
57           zone in the string you pass to "parse_datetime", then the resulting
58           "DateTime" will use that time zone.
59
60           You can optionally use an on_error parameter. This parameter has
61           three valid options:
62
63           ·   'undef'
64
65               (not undef, 'undef', it's a string not an undefined value)
66
67               This is the default behavior. The module will return undef
68               whenever it gets upset. The error can be accessed using the
69               $object->errstr method.  This is the ideal behaviour for
70               interactive use where a user might provide an illegal pattern
71               or a date that doesn't match the pattern.
72
73           ·   'croak'
74
75               (not croak, 'croak', it's a string, not a function)
76
77               This used to be the default behaviour. The module will croak
78               with an error message whenever it gets upset.
79
80           ·   sub{...} or \&subname
81
82               When given a code ref, the module will call that sub when it
83               gets upset.  The sub receives two parameters: the object and
84               the error message. Using these two it is possible to emulate
85               the 'undef' behavior. (Returning a true value causes the method
86               to return undef. Returning a false value causes the method to
87               bravely continue):
88
89               sub{$_[0]->{errmsg} = $_[1]; 1},
90

METHODS

92       This class offers the following methods.
93
94       ·   parse_datetime($string)
95
96           Given a string in the pattern specified in the constructor, this
97           method will return a new "DateTime" object.
98
99           If given a string that doesn't match the pattern, the formatter
100           will croak or return undef, depending on the setting of on_error in
101           the constructor.
102
103       ·   format_datetime($datetime)
104
105           Given a "DateTime" object, this methods returns a string formatted
106           in the object's format. This method is synonymous with "DateTime"'s
107           strftime method.
108
109       ·   locale($locale)
110
111           When given a locale or "DateTime::Locale" object, this method sets
112           its locale appropriately. If the locale is not understood, the
113           method will croak or return undef (depending on the setting of
114           on_error in the constructor)
115
116           If successful this method returns the current locale. (After
117           processing as above).
118
119       ·   pattern($strptime_pattern)
120
121           When given a pattern, this method sets the object's pattern. If the
122           pattern is invalid, the method will croak or return undef
123           (depending on the value of the "on_error" parameter)
124
125           If successful this method returns the current pattern. (After
126           processing as above)
127
128       ·   time_zone($time_zone)
129
130           When given a name, offset or "DateTime::TimeZone" object, this
131           method sets the object's time zone. This effects the "DateTime"
132           object returned by parse_datetime
133
134           If the time zone is invalid, the method will croak or return undef
135           (depending on the value of the "on_error" parameter)
136
137           If successful this method returns the current time zone. (After
138           processing as above)
139
140       ·   errmsg
141
142           If the on_error behavior of the object is 'undef', error messages
143           with this method so you can work out why things went wrong.
144
145           This code emulates a $DateTime::Format::Strptime with the
146           "on_error" parameter equal to 'croak':
147
148           "$Strp-"pattern($pattern) or die
149           $DateTime::Format::Strptime::errmsg>
150

EXPORTS

152       There are no methods exported by default, however the following are
153       available:
154
155       ·   strptime($strptime_pattern, $string)
156
157           Given a pattern and a string this function will return a new
158           "DateTime" object.
159
160       ·   strftime($strftime_pattern, $datetime)
161
162           Given a pattern and a "DateTime" object this function will return a
163           formatted string.
164

STRPTIME PATTERN TOKENS

166       The following tokens are allowed in the pattern string for strptime
167       (parse_datetime):
168
169       ·   %%
170
171           The % character.
172
173       ·   %a or %A
174
175           The weekday name according to the current locale, in abbreviated
176           form or the full name.
177
178       ·   %b or %B or %h
179
180           The month name according to the current locale, in abbreviated form
181           or the full name.
182
183       ·   %C
184
185           The century number (0-99).
186
187       ·   %d or %e
188
189           The day of month (1-31).
190
191       ·   %D
192
193           Equivalent to %m/%d/%y. (This is the American style date, very
194           confusing to non-Americans, especially since %d/%m/%y is    widely
195           used in Europe.  The ISO 8601 standard pattern is %F.)
196
197       ·   %F
198
199           Equivalent to %Y-%m-%d. (This is the ISO style date)
200
201       ·   %g
202
203           The year corresponding to the ISO week number, but without the
204           century (0-99).
205
206       ·   %G
207
208           The year corresponding to the ISO week number.
209
210       ·   %H
211
212           The hour (0-23).
213
214       ·   %I
215
216           The hour on a 12-hour clock (1-12).
217
218       ·   %j
219
220           The day number in the year (1-366).
221
222       ·   %m
223
224           The month number (1-12).
225
226       ·   %M
227
228           The minute (0-59).
229
230       ·   %n
231
232           Arbitrary whitespace.
233
234       ·   %N
235
236           Nanoseconds. For other sub-second values use "%[number]N".
237
238       ·   %p
239
240           The equivalent of AM or PM according to the locale in use. (See
241           DateTime::Locale)
242
243       ·   %r
244
245           Equivalent to %I:%M:%S %p.
246
247       ·   %R
248
249           Equivalent to %H:%M.
250
251       ·   %s
252
253           Number of seconds since the Epoch.
254
255       ·   %S
256
257           The second (0-60; 60 may occur for leap seconds. See
258           DateTime::LeapSecond).
259
260       ·   %t
261
262           Arbitrary whitespace.
263
264       ·   %T
265
266           Equivalent to %H:%M:%S.
267
268       ·   %U
269
270           The week number with Sunday the first day of the week (0-53). The
271           first Sunday of January is the first day of week 1.
272
273       ·   %u
274
275           The weekday number (1-7) with Monday = 1. This is the "DateTime"
276           standard.
277
278       ·   %w
279
280           The weekday number (0-6) with Sunday = 0.
281
282       ·   %W
283
284           The week number with Monday the first day of the week (0-53). The
285           first Monday of January is the first day of week 1.
286
287       ·   %y
288
289           The year within century (0-99). When a century is not otherwise
290           specified, values in the range 69-99 refer to years in the
291           twentieth century (1969-1999); values in the range 00-68 refer to
292           years in the twenty-first century (2000-2068).
293
294       ·   %Y
295
296           The year, including century (for example, 1991).
297
298       ·   %z
299
300           An RFC-822/ISO 8601 standard time zone specification. (For example
301           +1100) [See note below]
302
303       ·   %Z
304
305           The timezone name. (For example EST -- which is ambiguous) [See
306           note below]
307
308       ·   %O
309
310           This extended token allows the use of Olson Time Zone names to
311           appear in parsed strings. NOTE: This pattern cannot be passed to
312           "DateTime"'s "strftime()" method, but can be passed to
313           "format_datetime()".
314

BUGS

316       Please report any bugs or feature requests to
317       "bug-datetime-format-strptime@rt.cpan.org", or through the web
318       interface at <http://rt.cpan.org>. I will be notified, and then you'll
319       automatically be notified of progress on your bug as I make changes.
320

COPYRIGHT & LICENSE

322       Copyright X Rick Measham, 2003-2009, Dave Rolsky 2010. All rights
323       reserved.
324
325       This library is free software; you can redistribute it and/or modify it
326       under the same terms as Perl itself.
327
328       The full text of the licenses can be found in the LICENSE file included
329       with this module.
330

AUTHOR

332       Dave Rolsky <autarch@urth.org>
333
334       Originally created by Rick Measham.
335