---
name: "Types::DateTime"
section: "3pm"
platform: "linux"
package: "libtypes-datetime-perl"
version: "0.002-3"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Types::DateTime"
---

# Types::DateTime(3pm)

type constraints and coercions for datetime objects

## NAME

Types::DateTime - type constraints and coercions for datetime objects

## SYNOPSIS

```
   package FroobleGala;

   use Moose;
   use Types::DateTime -all;

   has start_date => (
      is      => 'ro',
      isa     => DateTimeUTC->plus_coercions( Format['ISO8601'] ),
      coerce  => 1,
   );
```

## DESCRIPTION

Types::DateTime is a type constraint library suitable for use with Moo/Moose attributes, Kavorka sub signatures, and so forth.

### Types

This module provides some type constraints broadly compatible with those provided by MooseX::Types::DateTime, plus a couple of extra type constraints.

- "DateTime"

  A class type for DateTime. Coercions from:

  - from "Num"

    Uses "from\_epoch" in DateTime. Floating values will be used for sub-second precision, see DateTime for details.

  - from "HashRef"

    Calls "new" in DateTime or "from\_epoch" in DateTime as appropriate, passing the hash as arguments.

  - from "Now"

    Uses "now" in DateTime.

  - from "InstanceOf\['DateTime::Tiny'\]"

    Inflated using "DateTime" in DateTime::Tiny.

- "Duration"

  A class type for DateTime::Duration. Coercions from:

  - from "Num"

    Uses "new" in DateTime::Duration and passes the number as the `"seconds"` argument.

  - from "HashRef"

    Calls "new" in DateTime::Duration with the hash entries as arguments.

- "Locale"

  A class type for DateTime::Locale. Coercions from:

  - from "Str"

    The string is treated as a language tag (e.g. `"en"` or `"he_IL"`) and given to "load" in DateTime::Locale.

  - from "InstanceOf\['Locale::Maketext'\]"

    The `"Locale::Maketext/language_tag"` attribute will be used with "load" in DateTime::Locale.

- "TimeZone"

  A class type for DateTime::TimeZone. Coercions from:

  - from "Str"

    Treated as a time zone name or offset. See "USAGE" in DateTime::TimeZone for more details on the allowed values.

    Delegates to "new" in DateTime::TimeZone with the string as the `"name"` argument.

- "Now"

  Type constraint with only one allowed value, the string "now".

  This is exported for compatibility with MooseX::Types::DateTime, which exports such a constraint, even though it is not documented.

- "DateTimeWithZone"

  A subtype of `"DateTime"` for objects with a defined (non-floating) time zone.

  This type constraint inherits its coercions from `"DateTime"`.

- "DateTimeWithZone\[\`a\]"

  The `"DateTimeWithZone"` type constraint may be parameterized with a DateTime::TimeZone object, or a string that can be coerced into one.

  ```
     has start_date => (
        is      => 'ro',
        isa     => DateTimeWithZone['Europe/London'],
        coerce  => 1,
     );
  ```

  This type constraint inherits its coercions from `"DateTime"`, and will additionally call "set\_time\_zone" in DateTime to shift objects into the correct timezone.

- "DateTimeUTC"

  Shortcut for `"DateTimeWithZone["UTC"]"`.

### Named Coercions

It is hoped that Type::Tiny will help avoid the proliferation of modules like MooseX::Types::DateTimeX, MooseX::Types::DateTime::ButMaintained, and MooseX::Types::DateTime::MoreCoercions. It makes it very easy to add coercions to a type constraint at the point of use:

```
   has start_date => (
      is      => 'ro',
      isa     => DateTime->plus_coercions(
         InstanceOf['MyApp::DT'] => sub { $_->to_DateTime }
      ),
      coerce  => 1,
   );
```

Even easier, this module exports some named coercions.

- "Format\[\`a\]"

  May be passed an object providing a `"parse_datetime"` method, or a class name from the `"DateTime::Format::"` namespace (upon which `"new"` will be called).

  For example:

  ```
     DateTime->plus_coercions( Format['ISO8601'] )
  ```

  Or:

  ```
     DateTimeUTC->plus_coercions(
        Format[
           DateTime::Format::Natural->new(lang => 'en')
        ]
     )
  ```

- "Strftime\[\`a\]"

  A pattern for serializing a DateTime object into a string using "strftime" in DateTime.

  ```
     Str->plus_coercions( Strftime['%a %e %b %Y'] );
  ```

- "ToISO8601"

  A coercion for serializing a DateTime object into a string using "iso8601" in DateTime.

  ```
     Str->plus_coercions( ToISO8601 );
  ```

## BUGS

Please report any bugs to \<http://rt.cpan.org/Dist/Display.html?Queue=Types-DateTime\>.

## SEE ALSO

MooseX::Types::DateTime, Type::Tiny::Manual, DateTime, DateTime::Duration, DateTime::Locale, DateTime::TimeZone.

## AUTHOR

Toby Inkster \<tobyink@cpan.org\>.

## COPYRIGHT AND LICENCE

This software is copyright (c) 2014, 2017 by Toby Inkster.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

## DISCLAIMER OF WARRANTIES

THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.