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 pat‐
7       terns
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         # Croak when things go wrong:
24         my $Strp = new DateTime::Format::Strptime(
25                                       pattern         => '%T',
26                                       locale      => 'en_AU',
27                                       time_zone       => 'Australia/Melbourne',
28                                       on_error        => 'croak',
29                               );
30
31         $newpattern = $Strp->pattern('%Q');
32         # Unidentified token in pattern: %Q in %Q at line 34 of script.pl
33
34         # Do something else when things go wrong:
35         my $Strp = new DateTime::Format::Strptime(
36                                       pattern         => '%T',
37                                       locale      => 'en_AU',
38                                       time_zone       => 'Australia/Melbourne',
39                                       on_error        => \&phone_police,
40                               );
41

DESCRIPTION

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

CONSTRUCTOR

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

METHODS

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

EXPORTS

139       There are no methods exported by default, however the following are
140       available:
141
142       * strptime($strptime_pattern, $string)
143           Given a pattern and a string this function will return a new "Date‐
144           Time" object.
145
146       * strftime($strftime_pattern, $datetime)
147           Given a pattern and a "DateTime" object this function will return a
148           formatted string.
149

STRPTIME PATTERN TOKENS

151       The following tokens are allowed in the pattern string for strptime
152       (parse_datetime):
153
154       * %%
155           The % character.
156
157       * %a or %A
158           The weekday name according to the current locale, in abbreviated
159           form or the full name.
160
161       * %b or %B or %h
162           The month name according to the current locale, in abbreviated form
163           or the full name.
164
165       * %C
166           The century number (0-99).
167
168       * %d or %e
169           The day of month (1-31).
170
171       * %D
172           Equivalent to %m/%d/%y. (This is the American style date, very con‐
173           fusing to non-Americans, especially since %d/%m/%y is    widely
174           used in Europe.  The ISO 8601 standard pattern is %F.)
175
176       * %F
177           Equivalent to %Y-%m-%d. (This is the ISO style date)
178
179       * %g
180           The year corresponding to the ISO week number, but without the cen‐
181           tury (0-99).
182
183       * %G
184           The year corresponding to the ISO week number.
185
186       * %H
187           The hour (0-23).
188
189       * %I
190           The hour on a 12-hour clock (1-12).
191
192       * %j
193           The day number in the year (1-366).
194
195       * %m
196           The month number (1-12).
197
198       * %M
199           The minute (0-59).
200
201       * %n
202           Arbitrary whitespace.
203
204       * %N
205           Nanoseconds. For other sub-second values use "%[number]N".
206
207       * %p
208           The equivalent of AM or PM according to the locale in use. (See
209           DateTime::Locale)
210
211       * %r
212           Equivalent to %I:%M:%S %p.
213
214       * %R
215           Equivalent to %H:%M.
216
217       * %s
218           Number of seconds since the Epoch.
219
220       * %S
221           The second (0-60; 60 may occur for leap seconds. See Date‐
222           Time::LeapSecond).
223
224       * %t
225           Arbitrary whitespace.
226
227       * %T
228           Equivalent to %H:%M:%S.
229
230       * %U
231           The week number with Sunday the first day of the week (0-53). The
232           first Sunday of January is the first day of week 1.
233
234       * %u
235           The weekday number (1-7) with Monday = 1. This is the "DateTime"
236           standard.
237
238       * %w
239           The weekday number (0-6) with Sunday = 0.
240
241       * %W
242           The week number with Monday the first day of the week (0-53). The
243           first Monday of January is the first day of week 1.
244
245       * %y
246           The year within century (0-99). When a century is not otherwise
247           specified, values in the range 69-99 refer to years in the twen-
248           tieth century (1969-1999); values in the range 00-68 refer to years
249           in the twenty-first century (2000-2068).
250
251       * %Y
252           The year, including century (for example, 1991).
253
254       * %z
255           An RFC-822/ISO 8601 standard time zone specification. (For example
256           +1100) [See note below]
257
258       * %Z
259           The timezone name. (For example EST -- which is ambiguous) [See
260           note below]
261
262       * %O
263           This extended token allows the use of Olson Time Zone names to
264           appear in parsed strings. NOTE: This pattern cannot be passed to
265           "DateTime"'s "strftime()" method, but can be passed to "for‐
266           mat_datetime()".
267

NOTES

269       * on_error
270           Default behavior of this module is now to return undef on erroring.
271

SUPPORT

273       Support for this module is provided via the datetime@perl.org email
274       list. See http://lists.perl.org/ for more details.
275
276       Alternatively, log them via the CPAN RT system via the web or email:
277
278               bug-datetime-format-strptime@rt.cpan.org
279
280       This makes it much easier for me to track things and thus means your
281       problem is less likely to be neglected.
282

LICENSE AND COPYRIGHT

284       Copyright © Rick Measham, 2003-2005. All rights reserved.
285
286       This library is free software; you can redistribute it and/or modify it
287       under the same terms as Perl itself.
288
289       The full text of the licenses can be found in the LICENCE file included
290       with this module.
291

AUTHOR

293       Rick Measham <rickm@cpan.org>
294