---
name: "Rose::Object::MakeMethods::DateTime"
section: "3pm"
platform: "linux"
package: "librose-object-perl"
version: "0.860-2"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Rose::Object::MakeMethods::DateTime"
---

# Rose::Object::MakeMethods::DateTime(3pm)

Create methods that store DateTime objects.

## NAME

Rose::Object::MakeMethods::DateTime - Create methods that store DateTime objects.

## SYNOPSIS

```
  package MyObject;
  use Rose::Object::MakeMethods::DateTime
  (
    datetime =>
    [
      'birthday',
      'arrival' => { tz => 'UTC' }
    ],
  );
  ...
  $obj = MyObject->new(birthday => '1/24/1984 1am');
  $dt = $obj->birthday; # DateTime object
  $bday = $obj->birthday(format => '%B %E'); # 'January 24th'
  # Shortcut for $obj->birthday->clone->truncate(to => 'month');
  $month = $obj->birthday(truncate => 'month');
  $obj->birthday('blah');       # croaks - invalid date!
  $obj->birthday('1999-04-31'); # croaks - invalid date!
```

## DESCRIPTION

Rose::Object::MakeMethods::DateTime is a method maker that inherits from Rose::Object::MakeMethods.  See the Rose::Object::MakeMethods documentation to learn about the interface.  The method types provided by this module are described below.  All methods work only with hash-based objects.

## METHODS TYPES

- **datetime**

  Create get/set methods for scalar attributes that store DateTime objects.

  - Options

    - "hash\_key"

      The key inside the hash-based object to use for the storage of this attribute. Defaults to the name of the method.

    - "init\_method"

      The name of the method to call when initializing the value of an undefined attribute.  This option is only applicable when using the `"get_set_init"` interface. Defaults to the method name with the prefix `"init_"` added.

      This method should return a value that can be parsed by Rose::DateTime::Util's the **parse\_date()** function. If the return value is a DateTime object, it will have its time zone set (see the `"tz"` option below) using DateTime's **set\_time\_zone()** method.

    - "interface"

      Chooses one of the two possible interfaces.  Defaults to `"get_set"`.

    - "tz"

      The time zone of the DateTime object to be stored.  If present, this value will be passed as the second argument to Rose::DateTime::Util's the **parse\_date()** function when creating DateTime objects for storage. If absent, DateTime objects will use the default time zone of the Rose::DateTime::Util class, which is set by Rose::DateTime::Util's **time\_zone()** class method.  See the Rose::DateTime::Util documentation for more information.

  - Interfaces

    - "get\_set"

      Creates a get/set accessor method for an object attribute that stores a DateTime object.

      When called with a single argument, the argument is passed through Rose::DateTime::Util's **parse\_date()** function in order to create the DateTime object that is stored.  The current value of the attribute is returned.  Passing a value that is not understood by Rose::DateTime::Util's **parse\_date()** function causes a fatal error.

      When called with two arguments and the first argument is the string 'format', then the second argument is taken as a format specifier which is passed to Rose::DateTime::Util's **format\_date()** function.  The formatted string is returned.  In other words, this:

      ```
          $obj->birthday(format => '%m/%d/%Y');
      ```

      Is just a shortcut for this:

      ```
          Rose::DateTime::Util::format_date($obj->birthday,
                                            '%m/%d/%Y');
      ```

      When called with two arguments and the first argument is the string 'truncate', then the second argument is taken as a truncation specifier which is passed to DateTime's **truncate()** method called on a clone of the existing DateTime object.  The cloned, truncated DateTime object is returned.  In other words, this:

      ```
          $obj->birthday(truncate => 'month');
      ```

      Is just a shortcut for this:

      ```
          $obj->birthday->clone->truncate(to => 'month');
      ```

      Passing more than two arguments or passing two arguments where the first argument is not 'format' or 'truncate' will cause a fatal error.

    - "get\_set\_init"

      Behaves like the `"get_set"` interface unless the value of the attribute is undefined.  In that case, the method specified by the `"init_method"` option is called, the return value is passed through Rose::DateTime::Util's **parse\_date()** function, and the attribute is set to the return value.  An init method that returns a value that is not understood by Rose::DateTime::Util's **parse\_date()** function will cause a fatal error.

  Example:

  ```
      package MyObject;
      use Rose::Object::MakeMethods::DateTime
      (
        datetime =>
        [
          'birthday',
          'arrival' => { tz => 'UTC' }
        ],
        'datetime --get_set_init' =>
        [
          'departure' => { tz => 'UTC' }
        ],
      );
      sub init_departure
      {
        DateTime->new(month => 1,
                      day   => 10,
                      year  => 2000,
                      time_zone => 'America/Chicago');
      }
      ...
      $obj = MyObject->new(birthday => '1/24/1984 1am');
      $dt = $obj->birthday; # DateTime object
      $bday = $obj->birthday(format => '%B %E'); # 'January 24th'
      # Shortcut for $obj->birthday->clone->truncate(to => 'month');
      $month = $obj->birthday(truncate => 'month');
      $obj->birthday('blah');       # croaks - invalid date!
      $obj->birthday('1999-04-31'); # croaks - invalid date!
      # DateTime object with time zone set to UTC
      $dt = $obj->arrival('2005-21-01 4pm');
      # DateTime object with time zone set to UTC, not America/Chicago!
      #   Start with 2000-01-10T00:00:00 America/Chicago,
      #   then set_time_zone('UTC'),
      #   which results in: 2000-01-10T06:00:00 UTC
      $dt = $obj->departure;
      print $dt; # "2000-01-10T06:00:00"
  ```

## AUTHOR

John C. Siracusa (siracusa@gmail.com)

## LICENSE

Copyright (c) 2010 by John C. Siracusa.  All rights reserved.  This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.