1Rose::DateTime::Util(3)User Contributed Perl DocumentatioRnose::DateTime::Util(3)
2
6 Rose::DateTime::Util - Some simple DateTime wrapper functions.
7
9 use Rose::DateTime::Util qw(:all);
10 $now = parse_date('now');
12 $then = parse_date('12/25/2001 11pm');
13 print $now->day_of_week; # e.g., "Monday"
15 # "December 25th 2001 at 11:00:00 PM"
17 $date_text = format_date($then, "%B %E %Y at %t");
18
20 Rose::DateTime::Util is a thin wrapper around DateTime that provides a
21 very simple date parser and a few extra date formatting options.
22
24 Rose::DateTime::Util does not export any function names by default.
25 The 'all' tag:
27 use Rose::DateTime::Util qw(:all);
29 will cause the following function names to be imported:
31 format_date()
33 parse_date()
34 parse_epoch()
35 parse_european_date()
36
38 error
39 Returns a message describing the last error that occurred.
40 european_dates [BOOL]
42 Get or set a boolean flag that determines how "xx/xx/xxxx" dates
43 are parsed by the parse_date function. If set to a false-but-
44 defined value, then such dates are parsed as "mm/dd/yyyy". If set
45 to true, then they're parsed as "dd/mm/yyyy". If set to undef,
46 then the attribute resets to its initial value, which is determined
47 as described below.
48 The initial value of this attribute is chosen based on the current
50 locale as stored in DateTime's DefaultLocale setting. This
51 initial value is looked up only once. Any subsequent changes to
52 DateTime's DefaultLocale setting will be ignored until/unless this
53 attribute is reset to undef.
54 time_zone [TZ]
56 Get or set the default time zone. This value is passed to
57 DateTime->new(...) as the value of the "time_zone" parameter when
58 parse_date() creates the DateTime object that it returns. The
59 default value is "floating".
60
62 format_date DATETIME, FORMAT1, FORMAT2 ...
63 Takes a DateTime object and a list of format strings. In list
64 context, it returns a list of strings with the formats
65 interpolated. In scalar context, it returns a single string
66 constructed by joining all of the list-context return values with
67 single spaces. Examples:
68 # $s = 'Friday 5PM'
70 $s = format_date(parse_date('1/23/2004 17:00'), '%A, %I%p');
71 # @s = ('Friday', 5, 'PM')
73 @s = format_date(parse_date('1/23/2004 17:00'), '%A', '%I', '%p');
74 # $s = 'Friday 5 PM'
76 $s = format_date(parse_date('1/23/2004 17:00'), '%A', '%I', '%p');
77 Returns undef on failure, or if passed an undefined value for
79 DATETIME. An exception will be raised if the DATETIME argument is
80 defined, but is not a DateTime object.
81 The supported formats are mostly based on those supported by
83 DateTime's strftime() method. Rose::DateTime::Util calls
84 DateTime's strftime() method when interpolating these formats.
85 Note that the %t and %F formats are not passed to strftime(), but
87 are handled by Rose::DateTime::Util instead. See the "Non-standard
88 formats" section below.
89 The strftime()-compatible formats listed below have been
91 transcribed from the DateTime documentation for the sake of
92 convenience, but the DateTime documentation is the definitive
93 source.
94 Using any format strings not in the strftime()-compatible set will
96 be slightly slower.
97 strftime()-compatible formats
99 • %a
101 The abbreviated weekday name.
103 • %A
105 The full weekday name.
107 • %b
109 The abbreviated month name.
111 • %B
113 The full month name.
115 • %c
117 The default datetime format for the object's locale.
119 • %C
121 The century number (year/100) as a 2-digit integer.
123 • %d
125 The day of the month as a decimal number (range 01 to 31).
127 • %D
129 Equivalent to %m/%d/%y. This is not a good standard format if
131 you have want both Americans and Europeans to understand the
132 date!
133 • %e
135 Like %d, the day of the month as a decimal number, but a
137 leading zero is replaced by a space.
138 • %G
140 The ISO 8601 year with century as a decimal number. The
142 4-digit year corresponding to the ISO week number (see %V).
143 This has the same format and value as %y, except that if the
144 ISO week number belongs to the previous or next year, that year
145 is used instead. (TZ)
146 • %g
148 Like %G, but without century, i.e., with a 2-digit year
150 (00-99).
151 • %h
153 Equivalent to %b.
155 • %H
157 The hour as a decimal number using a 24-hour clock (range 00 to
159 23).
160 • %I
162 The hour as a decimal number using a 12-hour clock (range 01 to
164 12).
165 • %j
167 The day of the year as a decimal number (range 001 to 366).
169 • %k
171 The hour (24-hour clock) as a decimal number (range 0 to 23);
173 single digits are preceded by a blank. (See also %H.)
174 • %l
176 The hour (12-hour clock) as a decimal number (range 1 to 12);
178 single digits are preceded by a blank. (See also %I.)
179 • %m
181 The month as a decimal number (range 01 to 12).
183 • %M
185 The minute as a decimal number (range 00 to 59).
187 • %n
189 A newline character.
191 • %N
193 The fractional seconds digits. Default is 9 digits
195 (nanoseconds).
196 %3N milliseconds (3 digits)
198 %6N microseconds (6 digits)
199 %9N nanoseconds (9 digits)
200 • %p
202 Either `AM' or `PM' according to the given time value, or the
204 corresponding strings for the current locale. Noon is treated
205 as `pm' and midnight as `am'.
206 • %P
208 Like %p but in lowercase: `am' or `pm' or a corresponding
210 string for the current locale.
211 • %r
213 The time in a.m. or p.m. notation. In the POSIX locale this
215 is equivalent to `%I:%M:%S %p'.
216 • %R
218 The time in 24-hour notation (%H:%M). (SU) For a version
220 including the seconds, see %T below.
221 • %s
223 The number of seconds since the epoch.
225 • %S
227 The second as a decimal number (range 00 to 61).
229 • %T
231 The time in 24-hour notation (%H:%M:%S).
233 • %u
235 The day of the week as a decimal, range 1 to 7, Monday being 1.
237 See also %w.
238 • %U
240 The week number of the current year as a decimal number, range
242 00 to 53, starting with the first Sunday as the first day of
243 week 01. See also %V and %W.
244 • %V
246 The ISO 8601:1988 week number of the current year as a decimal
248 number, range 01 to 53, where week 1 is the first week that has
249 at least 4 days in the current year, and with Monday as the
250 first day of the week. See also %U and %W.
251 • %w
253 The day of the week as a decimal, range 0 to 6, Sunday being 0.
255 See also %u.
256 • %W
258 The week number of the current year as a decimal number, range
260 00 to 53, starting with the first Monday as the first day of
261 week 01.
262 • %x
264 The default date format for the object's locale.
266 • %X
268 The default time format for the object's locale.
270 • %y
272 The year as a decimal number without a century (range 00 to
274 99).
275 • %Y
277 The year as a decimal number including the century.
279 • %z
281 The time-zone as hour offset from UTC. Required to emit
283 RFC822-conformant dates (using "%a, %d %b %Y %H:%M:%S %z").
284 • %Z
286 The time zone or name or abbreviation.
288 • %%
290 A literal `%' character.
292 • %{method}
294 Any method name may be specified using the format "%{method}"
296 name where "method" is a valid DateTime object method.
297 Non-standard formats
299 • %E
301 Day of the month word (1st, 2nd, 3rd, ... 31st)
303 • %f
305 Month number (1, 2, 3, ... 12)
307 • %F
309 "%A, %B %E %Y" (Wednesday, April 4th 2001)
311 • %i
313 Hour, 12-hour (1, 2, 3, ... 12)
315 • %t
317 Time as "%l:%M:%S %p" (1:23:45 PM)
319 parse_european_date TEXT [, TIMEZONE]
321 This function works the same as the parse_date function, except it
322 forces Eurpoean-style date parsing. In other words, this:
323 parse_european_date($date, $tz);
325 is equivalent to this:
327 # Save old value of the European date setting
329 my $save = Rose::DateTime::Util->european_dates;
330 # Turn European date parsing on
332 Rose::DateTime::Util->european_dates(1);
333 # Parse the date
335 parse_date($date, $tz);
336 # Restore the old European date setting
338 Rose::DateTime::Util->european_dates($save);
339 parse_date TEXT [, TIMEZONE]
341 Attempts to parse the date described by TEXT. Returns a DateTime
342 object, or undef on failure, with an error message available via
343 Rose::DateTime::Util->error().
344 If a DateTime object is passed in place of the TEXT argument, it is
346 returned as-is if there is no TIMEZONE argument, or after having
347 set_time_zone(TIMEZONE) called on it if there is a TIMEZONE
348 argument.
349 Since the time zone is not part of any of the supported date string
351 formats, parse_date() takes an optional TIMEZONE argument which is
352 passed to the DateTime constructor as the value of the "time_zone"
353 parameter. In the absence of a TIMEZONE argument to parwse_date(),
354 the time zone defaults to the value returned by the time_zone()
355 class method ("floating", by default)
356 The formats understood and their interpretations are listed below.
358 Square brackets are used to indicate optional portions of the
359 formats.
360 now Right now. Also valid with an exclamation point: "now!"
362 today
364 Today, at 00:00:00.
365 yyyy mm dd
367 yyyy mm dd [hh? am/pm]
368 yyyy mm dd [hh?:mm [am/pm]]
369 yyyy mm dd [hh?:mm:ss [am/pm]]
370 yyyy mm dd [hh?:mm:ss.nnnnnnnnn [am/pm]]
371 Exact date and time. Also valid without spaces, with hyphens
372 ("-"), periods ("."), or underscores ("_") between the year,
373 month, and day, and with a "T", hyphen, period, or underscore
374 between the date and time. The time is optional and defaults
375 to 00:00:00. The am/pm part is optional unless only the "hh"
376 (hours) part of the time is specified. Fractional seconds take
377 a maximum of 9 digits, but fewer are also acceptable.
378 mm/dd/yyyy [hh[:mm[:ss[.nnnnnnnnn]]]] [am/pm]
380 Exact date and time. Also valid with hyphens ("-"), periods
381 ("."), or underscores ("_") instead of slashes ("/"), and with
382 a "T", hyphen, period, or underscore between the date and time.
383 The time is optional and defaults to 00:00:00. The am/pm part
384 is optional. Fractional seconds take a maximum of 9 digits,
385 but fewer are also acceptable.
386 This format is only valid when european_dates is set to false
388 (which is the default).
389 dd/mm/yyyy [hh[:mm[:ss[.nnnnnnnnn]]]] [am/pm]
391 Exact date and time. Also valid with hyphens ("-"), periods
392 ("."), or underscores ("_") instead of slashes ("/"). The time
393 is optional and defaults to 00:00:00. The am/pm part is
394 optional. Fractional seconds take a maximum of 9 digits, but
395 fewer are also acceptable.
396 This format is only valid when european_dates is set to true.
398 [-]infinity
400 Positive or negative infinity. Case insensitive.
401 [-]dddddddddd[.nnnnnnnnn] seconds)
403 A positive or negative number with optional fractional seconds
404 is interpreted as seconds since the Unix epoch. Fractional
405 seconds take a maximum of 9 digits, but fewer are also
406 acceptable.
407 parse_epoch TEXT [, TIMEZONE]
409 This function is the same as parse_date except that it prefers Unix
410 epoch values in cases where this format conflicts with another.
411 Example:
412 $arg = '19991231';
414 $dt = parse_date($arg); # Dec 31, 1999
416 $dt = parse_epoch($arg); # Aug 20, 1970
417
419 DateTime, DateTime::TimeZone
420
422 John C. Siracusa (siracusa@gmail.com)
423
425 Copyright (c) 2010 by John C. Siracusa. All rights reserved. This
426 program is free software; you can redistribute it and/or modify it
427 under the same terms as Perl itself.
428perl v5.38.0 2023-07-21 Rose::DateTime::Util(3)