1Rose::DateTime::Util(3)User Contributed Perl DocumentatioRnose::DateTime::Util(3)
2
3
4

NAME

6       Rose::DateTime::Util - Some simple DateTime wrapper functions.
7

SYNOPSIS

9           use Rose::DateTime::Util qw(:all);
10
11           $now  = parse_date('now');
12           $then = parse_date('12/25/2001 11pm');
13
14           print $now->day_of_week; # e.g., "Monday"
15
16           # "December 25th 2001 at 11:00:00 PM"
17           $date_text = format_date($then, "%B %E %Y at %t");
18

DESCRIPTION

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

EXPORTS

24       Rose::DateTime::Util does not export any function names by default.
25
26       The 'all' tag:
27
28           use Rose::DateTime::Util qw(:all);
29
30       will cause the following function names to be imported:
31
32           format_date()
33           parse_date()
34           parse_epoch()
35           parse_european_date()
36

CLASS METHODS

38       error
39           Returns a message describing the last error that occurred.
40
41       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
49           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
55       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

FUNCTIONS

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
69             # $s = 'Friday 5PM'
70             $s = format_date(parse_date('1/23/2004 17:00'), '%A, %I%p');
71
72             # @s = ('Friday', 5, 'PM')
73             @s = format_date(parse_date('1/23/2004 17:00'), '%A', '%I', '%p');
74
75             # $s = 'Friday 5 PM'
76             $s = format_date(parse_date('1/23/2004 17:00'), '%A', '%I', '%p');
77
78           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
82           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
86           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
90           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
95           Using any format strings not in the strftime()-compatible set will
96           be slightly slower.
97
98           strftime()-compatible formats
99
100           •   %a
101
102               The abbreviated weekday name.
103
104           •   %A
105
106               The full weekday name.
107
108           •   %b
109
110               The abbreviated month name.
111
112           •   %B
113
114               The full month name.
115
116           •   %c
117
118               The default datetime format for the object's locale.
119
120           •   %C
121
122               The century number (year/100) as a 2-digit integer.
123
124           •   %d
125
126               The day of the month as a decimal number (range 01 to 31).
127
128           •   %D
129
130               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
134           •   %e
135
136               Like %d, the day of the month as a decimal number, but a
137               leading zero is replaced by a space.
138
139           •   %G
140
141               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
147           •   %g
148
149               Like %G, but without century, i.e., with a 2-digit year
150               (00-99).
151
152           •   %h
153
154               Equivalent to %b.
155
156           •   %H
157
158               The hour as a decimal number using a 24-hour clock (range 00 to
159               23).
160
161           •   %I
162
163               The hour as a decimal number using a 12-hour clock (range 01 to
164               12).
165
166           •   %j
167
168               The day of the year as a decimal number (range 001 to 366).
169
170           •   %k
171
172               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
175           •   %l
176
177               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
180           •   %m
181
182               The month as a decimal number (range 01 to 12).
183
184           •   %M
185
186               The minute as a decimal number (range 00 to 59).
187
188           •   %n
189
190               A newline character.
191
192           •   %N
193
194               The fractional seconds digits. Default is 9 digits
195               (nanoseconds).
196
197                 %3N   milliseconds (3 digits)
198                 %6N   microseconds (6 digits)
199                 %9N   nanoseconds  (9 digits)
200
201           •   %p
202
203               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
207           •   %P
208
209               Like %p but in lowercase: `am' or `pm' or a corresponding
210               string for the current locale.
211
212           •   %r
213
214               The time in a.m.  or p.m. notation.  In the POSIX locale this
215               is equivalent to `%I:%M:%S %p'.
216
217           •   %R
218
219               The time in 24-hour notation (%H:%M). (SU) For a version
220               including the seconds, see %T below.
221
222           •   %s
223
224               The number of seconds since the epoch.
225
226           •   %S
227
228               The second as a decimal number (range 00 to 61).
229
230           •   %T
231
232               The time in 24-hour notation (%H:%M:%S).
233
234           •   %u
235
236               The day of the week as a decimal, range 1 to 7, Monday being 1.
237               See also %w.
238
239           •   %U
240
241               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
245           •   %V
246
247               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
252           •   %w
253
254               The day of the week as a decimal, range 0 to 6, Sunday being 0.
255               See also %u.
256
257           •   %W
258
259               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
263           •   %x
264
265               The default date format for the object's locale.
266
267           •   %X
268
269               The default time format for the object's locale.
270
271           •   %y
272
273               The year as a decimal number without a century (range 00 to
274               99).
275
276           •   %Y
277
278               The year as a decimal number including the century.
279
280           •   %z
281
282               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
285           •   %Z
286
287               The time zone or name or abbreviation.
288
289           •   %%
290
291               A literal `%' character.
292
293           •   %{method}
294
295               Any method name may be specified using the format "%{method}"
296               name where "method" is a valid DateTime object method.
297
298           Non-standard formats
299
300           •   %E
301
302               Day of the month word (1st, 2nd, 3rd, ... 31st)
303
304           •   %f
305
306               Month number (1, 2, 3, ... 12)
307
308           •   %F
309
310               "%A, %B %E %Y" (Wednesday, April 4th 2001)
311
312           •   %i
313
314               Hour, 12-hour (1, 2, 3, ... 12)
315
316           •   %t
317
318               Time as "%l:%M:%S %p" (1:23:45 PM)
319
320       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
324               parse_european_date($date, $tz);
325
326           is equivalent to this:
327
328               # Save old value of the European date setting
329               my $save = Rose::DateTime::Util->european_dates;
330
331               # Turn European date parsing on
332               Rose::DateTime::Util->european_dates(1);
333
334               # Parse the date
335               parse_date($date, $tz);
336
337               # Restore the old European date setting
338               Rose::DateTime::Util->european_dates($save);
339
340       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
345           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
350           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
357           The formats understood and their interpretations are listed below.
358           Square brackets are used to indicate optional portions of the
359           formats.
360
361           now Right now.  Also valid with an exclamation point: "now!"
362
363           today
364               Today, at 00:00:00.
365
366           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
379           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
387               This format is only valid when european_dates is set to false
388               (which is the default).
389
390           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
397               This format is only valid when european_dates is set to true.
398
399           [-]infinity
400               Positive or negative infinity.  Case insensitive.
401
402           [-]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
408       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
413               $arg = '19991231';
414
415               $dt = parse_date($arg);  # Dec 31, 1999
416               $dt = parse_epoch($arg); # Aug 20, 1970
417

SEE ALSO

419       DateTime, DateTime::TimeZone
420

AUTHOR

422       John C. Siracusa (siracusa@gmail.com)
423

LICENSE

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.
428
429
430
431perl v5.36.0                      2023-01-20           Rose::DateTime::Util(3)
Impressum