1Rose::DB::Object::MakeMUestehrodCso:n:tDraitbeu(t3e)d PeRrolseD:o:cDuBm:e:nOtbajteicotn::MakeMethods::Date(3)
2
6 Rose::DB::Object::MakeMethods::Date - Create date-related methods for
7 Rose::DB::Object-derived objects.
8
10 package MyDBObject;
11 use base 'Rose::DB::Object';
13 use Rose::DB::Object::MakeMethods::Date
15 (
16 date =>
17 [
18 'start_date',
19 'end_date' => { default => '2005-01-30' }
20 ],
21 datetime =>
23 [
24 'date_created',
25 'other_date' => { type => 'datetime year to minute' },
26 ],
27 timestamp =>
29 [
30 'last_modified' => { default => '2005-01-30 12:34:56.123' }
31 ],
32 epoch =>
34 [
35 due_date => { default => '2003-01-02 12:34:56' },
36 event_start => { hires => 1 },
37 ],
38 );
39 ...
41 $o->start_date('2/3/2004 8am');
43 $dt = $o->start_date(truncate => 'day');
44 print $o->end_date(format => '%m/%d/%Y'); # 2005-01-30
46 $o->date_created('now');
48 $o->other_date('2001-02-20 12:34:56');
50 # 02/20/2001 12:34:00
52 print $o->other_date(format => '%m/%d/%Y %H:%M:%S');
53 print $o->last_modified(format => '%S.%5N'); # 56.12300
55 print $o->due_date(format => '%m/%d/%Y'); # 01/02/2003
57 $o->event_start('1980-10-11 6:00.123456');
59
61 "Rose::DB::Object::MakeMethods::Date" creates methods that deal with
62 dates, and inherits from Rose::Object::MakeMethods. See the
63 Rose::Object::MakeMethods documentation to learn about the interface.
64 The method types provided by this module are described below.
65 All method types defined by this module are designed to work with
67 objects that are subclasses of (or otherwise conform to the interface
68 of) Rose::DB::Object. In particular, the object is expected to have a
69 db method that returns a Rose::DB-derived object. See the
70 Rose::DB::Object documentation for more details.
71
73 date
74 Create get/set methods for date (year, month, day) attributes.
75 Options
77 "default"
78 Determines the default value of the attribute.
79 "hash_key"
81 The key inside the hash-based object to use for the storage
82 of this attribute. Defaults to the name of the method.
83 "interface"
85 Choose the interface. The default is "get_set".
86 "time_zone"
88 The time zone name, which must be in a format that is
89 understood by DateTime::TimeZone.
90 Interfaces
92 "get_set"
93 Creates a get/set method for a date (year, month, day)
94 attribute. When setting the attribute, the value is passed
95 through the parse_date method of the object's db attribute.
96 If that fails, the value is passed to
97 Rose::DateTime::Util's parse_date() function. If that
98 fails, a fatal error will occur.
99 The time zone of the DateTime object that results from a
101 successful parse is set to the value of the "time_zone"
102 option, if defined. Otherwise, it is set to the
103 server_time_zone value of the object's db attribute using
104 DateTime's set_time_zone method.
105 When saving to the database, the method will pass the
107 attribute value through the format_date method of the
108 object's db attribute before returning it. Otherwise, the
109 value is returned as-is.
110 This method is designed to allow date values to make a
112 round trip from and back into the database without ever
113 being "inflated" into DateTime objects. Any use of the
114 attribute (get or set) outside the context of loading from
115 or saving to the database will cause the value to be
116 "inflated" using the parse_date method of the object's db
117 attribute. If that fails, Rose::DateTime::Util's
118 parse_date() function is tried. If that fails, a fatal
119 error will occur.
120 If passed two arguments and the first argument is "format",
122 then the second argument is taken as a format string and
123 passed to Rose::DateTime::Util's format_date function along
124 with the current value of the date attribute. Example:
125 $o->start_date('2004-05-22');
127 print $o->start_date(format => '%A'); # "Saturday"
128 If passed two arguments and the first argument is
130 "truncate", then the second argument is taken as the value
131 of the "to" argument to DateTime's truncate method, which
132 is applied to a clone of the current value of the date
133 attribute, which is then returned. Example:
134 $o->start_date('2004-05-22');
136 # Equivalent to:
138 # $d = $o->start_date->clone->truncate(to => 'month')
139 $d = $o->start_date(truncate => 'month');
140 If the date attribute is undefined, then undef is returned
142 (i.e., no clone or call to truncate is made).
143 If a valid date keyword is passed as an argument, the value
145 will never be "inflated" but rather passed to the database
146 and returned to other code unmodified. That means that the
147 "truncate" and "format" calls described above will also
148 return the date keyword unmodified. See the Rose::DB
149 documentation for more information on date keywords.
150 "get"
152 Creates an accessor method for a date (year, month, day)
153 attribute. This method behaves like the "get_set" method,
154 except that the value cannot be set.
155 "set"
157 Creates a mutator method for a date (year, month, day)
158 attribute. This method behaves like the "get_set" method,
159 except that a fatal error will occur if no arguments are
160 passed. It also does not support the "truncate" and
161 "format" parameters.
162 Example:
164 package MyDBObject;
166 use base 'Rose::DB::Object';
168 use Rose::DB::Object::MakeMethods::Date
170 (
171 date =>
172 [
173 'start_date',
174 'end_date' => { default => '2005-01-30' }
175 ],
176 );
177 ...
179 $o->start_date('2/3/2004');
181 $dt = $o->start_date(truncate => 'week');
182 print $o->end_date(format => '%m/%d/%Y'); # 01/30/2005
184 datetime
186 Create get/set methods for "datetime" (year, month, day, hour,
187 minute, second) attributes.
188 Options
190 "default"
191 Determines the default value of the attribute.
192 "hash_key"
194 The key inside the hash-based object to use for the storage
195 of this attribute. Defaults to the name of the method.
196 "interface"
198 Choose the interface. The default is "get_set".
199 "time_zone"
201 The time zone name, which must be in a format that is
202 understood by DateTime::TimeZone.
203 "type"
205 The datetime variant as a string. Each space in the string
206 is replaced with an underscore "_", then the string is
207 appended to "format_" and "parse_" in order to form the
208 names of the methods called on the object's db attribute to
209 format and parse datetime values. The default is
210 "datetime", which means that the "format_datetime()" and
211 "parse_datetime()" methods will be used.
212 Any string that results in a set of method names that are
214 supported by the object's db attribute is acceptable.
215 Check the documentation for the class of the object's db
216 attribute for a list of valid method names.
217 Interfaces
219 "get_set"
220 Creates a get/set method for a "datetime" attribute. The
221 exact granularity of the "datetime" value is determined by
222 the value of the "type" option (see above).
223 When setting the attribute, the value is passed through the
225 "parse_TYPE()" method of the object's db attribute, where
226 "TYPE" is the value of the "type" option. If that fails,
227 the value is passed to Rose::DateTime::Util's parse_date()
228 function. If that fails, a fatal error will occur.
229 The time zone of the DateTime object that results from a
231 successful parse is set to the value of the "time_zone"
232 option, if defined. Otherwise, it is set to the
233 server_time_zone value of the object's db attribute using
234 DateTime's set_time_zone method.
235 When saving to the database, the method will pass the
237 attribute value through the "format_TYPE()" method of the
238 object's db attribute before returning it, where "TYPE" is
239 the value of the "type" option. Otherwise, the value is
240 returned as-is.
241 This method is designed to allow datetime values to make a
243 round trip from and back into the database without ever
244 being "inflated" into DateTime objects. Any use of the
245 attribute (get or set) outside the context of loading from
246 or saving to the database will cause the value to be
247 "inflated" using the "parse_TYPE()" method of the object's
248 db attribute, where "TYPE" is the value of the "type"
249 option. If that fails, Rose::DateTime::Util's parse_date()
250 function is tried. If that fails, a fatal error will
251 occur.
252 If passed two arguments and the first argument is "format",
254 then the second argument is taken as a format string and
255 passed to Rose::DateTime::Util's format_date function along
256 with the current value of the datetime attribute. Example:
257 $o->start_date('2004-05-22 12:34:56');
259 print $o->start_date(format => '%A'); # "Saturday"
260 If passed two arguments and the first argument is
262 "truncate", then the second argument is taken as the value
263 of the "to" argument to DateTime's truncate method, which
264 is applied to a clone of the current value of the datetime
265 attribute, which is then returned. Example:
266 $o->start_date('2004-05-22 04:32:01');
268 # Equivalent to:
270 # $d = $o->start_date->clone->truncate(to => 'month')
271 $d = $o->start_date(truncate => 'month');
272 If the datetime attribute is undefined, then undef is
274 returned (i.e., no clone or call to truncate is made).
275 If a valid datetime keyword is passed as an argument, the
277 value will never be "inflated" but rather passed to the
278 database and returned to other code unmodified. That means
279 that the "truncate" and "format" calls described above will
280 also return the datetime keyword unmodified. See the
281 Rose::DB documentation for more information on datetime
282 keywords.
283 "get"
285 Creates an accessor method for a "datetime" attribute.
286 This method behaves like the "get_set" method, except that
287 the value cannot be set.
288 "set"
290 Creates a mutator method for a "datetime" attribute. This
291 method behaves like the "get_set" method, except that a
292 fatal error will occur if no arguments are passed. It also
293 does not support the "truncate" and "format" parameters.
294 Example:
296 package MyDBObject;
298 use base 'Rose::DB::Object';
300 use Rose::DB::Object::MakeMethods::Date
302 (
303 datetime =>
304 [
305 'start_date',
306 'end_date' => { default => '2005-01-30 12:34:56' }
307 'other_date' => { type => 'datetime year to minute' },
308 ],
309 );
310 ...
312 $o->start_date('2/3/2004 8am');
314 $dt = $o->start_date(truncate => 'day');
315 # 01/30/2005 12:34:56
317 print $o->end_date(format => '%m/%d/%Y %H:%M:%S');
318 $o->other_date('2001-02-20 12:34:56');
320 # 02/20/2001 12:34:00
322 print $o->other_date(format => '%m/%d/%Y %H:%M:%S');
323 epoch
325 Create get/set methods for an attribute that stores seconds since
326 the Unix epoch.
327 Options
329 "default"
330 Determines the default value of the attribute.
331 "hash_key"
333 The key inside the hash-based object to use for the storage
334 of this attribute. Defaults to the name of the method.
335 "hires"
337 A boolean flag that indicates whether or not epoch values
338 should be stored with fractional seconds. If true, then up
339 to six (6) digits past the decimal point are preserved.
340 The default is false.
341 "interface"
343 Choose the interface. The default is "get_set".
344 "time_zone"
346 The time zone name, which must be in a format that is
347 understood by DateTime::TimeZone.
348 Interfaces
350 "get_set"
351 Creates a get/set method for an attribute that stores
352 seconds since the Unix epoch. When setting the attribute,
353 the value is passed through Rose::DateTime::Util's
354 parse_date() function. If that fails, a fatal error will
355 occur.
356 The time zone of the DateTime object that results from a
358 successful parse is set to the value of the "time_zone"
359 option, if defined. Otherwise, it is set to the
360 server_time_zone value of the object's db attribute using
361 DateTime's set_time_zone method.
362 When saving to the database, the epoch or hires_epoch
364 method will be called on the DateTime object, depending on
365 the value of the "hires" option. (See above.)
366 This method is designed to allow values to make a round
368 trip from and back into the database without ever being
369 "inflated" into DateTime objects. Any use of the attribute
370 (get or set) outside the context of loading from or saving
371 to the database will cause the value to be "inflated" using
372 Rose::DateTime::Util's parse_date() function. If that
373 fails, a fatal error will occur.
374 If passed two arguments and the first argument is "format",
376 then the second argument is taken as a format string and
377 passed to Rose::DateTime::Util's format_date function along
378 with the current value of the attribute. Example:
379 $o->due_date('2004-05-22');
381 print $o->due_date(format => '%A'); # "Saturday"
382 If passed two arguments and the first argument is
384 "truncate", then the second argument is taken as the value
385 of the "to" argument to DateTime's truncate method, which
386 is applied to a clone of the current value of the
387 attribute, which is then returned. Example:
388 $o->due_date('2004-05-22');
390 # Equivalent to:
392 # $d = $o->due_date->clone->truncate(to => 'month')
393 $d = $o->due_date(truncate => 'month');
394 If the attribute is undefined, then undef is returned
396 (i.e., no clone or call to truncate is made).
397 "get"
399 Creates an accessor method an attribute that stores seconds
400 since the Unix epoch. This method behaves like the
401 "get_set" method, except that the value cannot be set.
402 "set"
404 Creates a mutator method for an attribute that stores
405 seconds since the Unix epoch. This method behaves like the
406 "get_set" method, except that a fatal error will occur if
407 no arguments are passed. It also does not support the
408 "truncate" and "format" parameters.
409 Example:
411 package MyDBObject;
413 use base 'Rose::DB::Object';
415 use Rose::DB::Object::MakeMethods::Date
417 (
418 epoch =>
419 [
420 due_date => { default => '2003-01-02 12:34:56' },
421 event_start => { hires => 1 },
422 ],
423 );
424 ...
426 print $o->due_date(format => '%m/%d/%Y'); # 01/02/2003
428 $dt = $o->due_date(truncate => 'week');
429 $o->event_start('1980-10-11 6:00.123456');
431 print $o->event_start(format => '%6N'); # 123456
432 timestamp
434 Create get/set methods for "timestamp" (year, month, day, hour,
435 minute, second, fractional seconds) attributes.
436 Options
438 "default"
439 Determines the default value of the attribute.
440 "hash_key"
442 The key inside the hash-based object to use for the storage
443 of this attribute. Defaults to the name of the method.
444 "interface"
446 Choose the interface. The default interface is "get_set".
447 "time_zone"
449 A time zone name, which must be in a format that is
450 understood by DateTime::TimeZone.
451 Interfaces
453 "get_set"
454 Creates a get/set method for a "timestamp" (year, month,
455 day, hour, minute, second, fractional seconds) attribute.
456 When setting the attribute, the value is passed through the
457 "parse_timestamp()" method of the object's db attribute.
458 If that fails, the value is passed to
459 Rose::DateTime::Util's parse_date() function. If that
460 fails, a fatal error will occur.
461 The time zone of the DateTime object that results from a
463 successful parse is set to the value of the "time_zone"
464 option, if defined. Otherwise, it is set to the
465 server_time_zone value of the object's db attribute using
466 DateTime's set_time_zone method.
467 When saving to the database, the method will pass the
469 attribute value through the format_timestamp method of the
470 object's db attribute before returning it. Otherwise, the
471 value is returned as-is.
472 This method is designed to allow timestamp values to make a
474 round trip from and back into the database without ever
475 being "inflated" into DateTime objects. Any use of the
476 attribute (get or set) outside the context of loading from
477 or saving to the database will cause the value to be
478 "inflated" using the "parse_timestamp()" method of the
479 object's db attribute. If that fails,
480 Rose::DateTime::Util's parse_date() function is tried. If
481 that fails, a fatal error will occur.
482 If passed two arguments and the first argument is "format",
484 then the second argument is taken as a format string and
485 passed to Rose::DateTime::Util's format_date function along
486 with the current value of the timestamp attribute.
487 Example:
488 $o->start_date('2004-05-22 12:34:56.123');
490 print $o->start_date(format => '%A'); # "Saturday"
491 If passed two arguments and the first argument is
493 "truncate", then the second argument is taken as the value
494 of the "to" argument to DateTime's truncate method, which
495 is applied to a clone of the current value of the timestamp
496 attribute, which is then returned. Example:
497 $o->start_date('2004-05-22 04:32:01.456');
499 # Equivalent to:
501 # $d = $o->start_date->clone->truncate(to => 'month')
502 $d = $o->start_date(truncate => 'month');
503 If the timestamp attribute is undefined, then undef is
505 returned (i.e., no clone or call to truncate is made).
506 If a valid timestamp keyword is passed as an argument, the
508 value will never be "inflated" but rather passed to the
509 database and returned to other code unmodified. That means
510 that the "truncate" and "format" calls described above will
511 also return the timestamp keyword unmodified. See the
512 Rose::DB documentation for more information on timestamp
513 keywords.
514 "get"
516 Creates an accessor method for a "timestamp" (year, month,
517 day, hour, minute, second, fractional seconds) attribute.
518 This method behaves like the "get_set" method, except that
519 the value cannot be set.
520 "set"
522 Creates a mutator method for a "timestamp" (year, month,
523 day, hour, minute, second, fractional seconds) attribute.
524 This method behaves like the "get_set" method, except that
525 a fatal error will occur if no arguments are passed. It
526 also does not support the "truncate" and "format"
527 parameters.
528 Example:
530 package MyDBObject;
532 use base 'Rose::DB::Object';
534 use Rose::DB::Object::MakeMethods::Date
536 (
537 timestamp =>
538 [
539 'start_date',
540 'end_date' => { default => '2005-01-30 12:34:56.123' }
541 ],
542 );
543 ...
545 $o->start_date('2/3/2004 8am');
547 $dt = $o->start_date(truncate => 'day');
548 # 01/30/2005 12:34:56.12300
550 print $o->end_date(format => '%m/%d/%Y %H:%M:%S.%5N');
551 timestamp_without_time_zone
553 This is identical to the timestamp method described above, but with
554 the "time_zone" parameter always set to the value "floating". Any
555 attempt to set the "time_zone" parameter explicitly will cause a
556 fatal error.
557 timestamp_with_time_zone
559 Create get/set methods for "timestamp with time zone" (year, month,
560 day, hour, minute, second, fractional seconds, time zone)
561 attributes.
562 Options
564 "default"
565 Determines the default value of the attribute.
566 "hash_key"
568 The key inside the hash-based object to use for the storage
569 of this attribute. Defaults to the name of the method.
570 "interface"
572 Choose the interface. The default interface is "get_set".
573 "time_zone"
575 A time zone name, which must be in a format that is
576 understood by DateTime::TimeZone.
577 Interfaces
579 "get_set"
580 Creates a get/set method for a "timestamp with time zone"
581 (year, month, day, hour, minute, second, fractional
582 seconds, time zone) attribute. When setting the attribute,
583 the value is passed through the
584 "parse_timestamp_with_timezone()" method of the object's db
585 attribute. If that fails, the value is passed to
586 Rose::DateTime::Util's parse_date() function. If that
587 fails, a fatal error will occur.
588 The time zone of the DateTime object will be set according
590 to the successful parse of the "timestamp with time zone"
591 value. If the "time_zone" option is set, then the time
592 zone of the DateTime object is set to this value. Note
593 that this happens after the successful parse, which means
594 that this operation may change the time and/or date
595 according to the difference between the time zone of the
596 value as originally parsed and the new time zone set
597 according to the "time_zone" option.
598 When saving to the database, the method will pass the
600 attribute value through the format_timestamp_with_timezone
601 method of the object's db attribute before returning it.
602 Otherwise, the value is returned as-is.
603 This method is designed to allow timestamp values to make a
605 round trip from and back into the database without ever
606 being "inflated" into DateTime objects. Any use of the
607 attribute (get or set) outside the context of loading from
608 or saving to the database will cause the value to be
609 "inflated" using the "parse_timestamp_with_time_zone()"
610 method of the object's db attribute. If that fails,
611 Rose::DateTime::Util's parse_date() function is tried. If
612 that fails, a fatal error will occur.
613 If passed two arguments and the first argument is "format",
615 then the second argument is taken as a format string and
616 passed to Rose::DateTime::Util's format_date function along
617 with the current value of the timestamp attribute.
618 Example:
619 $o->start_date('2004-05-22 12:34:56.123');
621 print $o->start_date(format => '%A'); # "Saturday"
622 If passed two arguments and the first argument is
624 "truncate", then the second argument is taken as the value
625 of the "to" argument to DateTime's truncate method, which
626 is applied to a clone of the current value of the timestamp
627 attribute, which is then returned. Example:
628 $o->start_date('2004-05-22 04:32:01.456');
630 # Equivalent to:
632 # $d = $o->start_date->clone->truncate(to => 'month')
633 $d = $o->start_date(truncate => 'month');
634 If the timestamp attribute is undefined, then undef is
636 returned (i.e., no clone or call to truncate is made).
637 If a valid timestamp keyword is passed as an argument, the
639 value will never be "inflated" but rather passed to the
640 database and returned to other code unmodified. That means
641 that the "truncate" and "format" calls described above will
642 also return the timestamp keyword unmodified. See the
643 Rose::DB documentation for more information on timestamp
644 keywords.
645 "get"
647 Creates an accessor method for a "timestamp with time zone"
648 (year, month, day, hour, minute, second, fractional
649 seconds, time zone) attribute. This method behaves like
650 the "get_set" method, except that the value cannot be set.
651 "set"
653 Creates a mutator method for a "timestamp with time zone"
654 (year, month, day, hour, minute, second, fractional
655 seconds, time zone) attribute. This method behaves like
656 the "get_set" method, except that a fatal error will occur
657 if no arguments are passed. It also does not support the
658 "truncate" and "format" parameters.
659 Example:
661 package MyDBObject;
663 use base 'Rose::DB::Object';
665 use Rose::DB::Object::MakeMethods::Date
667 (
668 timestamp_with_timezone =>
669 [
670 'start_date',
671 'end_date' => { default => '2005-01-30 12:34:56.123' }
672 ],
673 );
674 ...
676 $o->start_date('2/3/2004 8am');
678 $dt = $o->start_date(truncate => 'day');
679 # 01/30/2005 12:34:56.12300
681 print $o->end_date(format => '%m/%d/%Y %H:%M:%S.%5N');
682
684 John C. Siracusa (siracusa@gmail.com)
685
687 Copyright (c) 2010 by John C. Siracusa. All rights reserved. This
688 program is free software; you can redistribute it and/or modify it
689 under the same terms as Perl itself.
690perl v5.34.0 2021-07R-o2s2e::DB::Object::MakeMethods::Date(3)