DateTimeX::Auto(3pm)

✨ DateTimeX::Auto ✨

okay bestie, gather round 💖 this is the DateTimeX::Auto page from the User Contributed Perl Documentation section of the manual (you know, the 3pm girlies 👑), and it's literally about using DateTime without ever having to call a constructor. no cap. let's get into it 🦋

---

🌸 NAME 🌸

DateTimeX::Auto — use DateTime without needing to call constructors 💅

---

🎀 SYNOPSIS 🎀

use DateTimeX::Auto -auto;

my $ga_start = '2000-04-06' + 'P10Y';
printf("%s %s\n", $ga_start, ref $ga_start);  # 2010-04-06 DateTime

{
  no DateTimeX::Auto;
  my $string = '2000-04-06';
  printf( "%s\n", ref($string) ? 'Ref' : 'NoRef' );  # NoRef
}

like... look at that. '2000-04-06' + 'P10Y' and boom, you got a DateTime. and then inside the block, no DateTimeX::Auto; and suddenly it's just a plain string again. the range of it 🌈

---

💖 DESCRIPTION 💖

so. DateTime is awesome, obviously, but constructing DateTime objects can be so annoying 😭 like you either gotta reach for one of the formatter modules, or you're sitting there calling DateTime->new() with a whole bunch of values like it's a group project. and if your code is just full of constant dates?? bestie. DateTimeX::Auto makes all of that a little bit simpler 🫶

here's the tea ☕ — it uses overload to overload the q() operator, which automatically turns all string constants matching particular regular expressions into DateTime objects. it also overloads stringification so that your DateTime objects get stringified back to exactly the format they were given in. iconic behaviour, honestly ✨

the date formats supported are:

 yyyy-mm-dd
 yyyy-mm-ddZ
 yyyy-mm-ddThh:mm:ss
 yyyy-mm-ddThh:mm:ssZ

that optional trailing 'Z'? it puts the datetime into the UTC timezone ⭐ otherwise the datetime will be in DateTime's default (floating) timezone. iykyk.

Fractional seconds are also supported, to an arbitrary number of decimal places 🍓 BUT — and this is important bestie — since DateTime only supports nanosecond precision, any digits after the ninth will be zeroed out. periodt.

my $dt         ='1234-12-12T12:34:56.123456789123456789';
print "$dt\n"; # 1234-12-12T12:34:56.123456789000000000

objects are blessed into the DateTimeX::Auto::DateTime class, which inherits from DateTime 👑 they use UNIVERSAL::ref (if installed) to masquerade as plain DateTime objects, main character energy fr fr.

print ref('2000-01-01')."\n";   # DateTime

Additionally, ISO 8601 durations are supported 💜

my $dt = '2000-01-01';
say( $dt + 'P4Y2M12D' );  # 2004-03-13

⚠️ fair warning: durations are possibly not quite as clever at preserving the incoming string formatting. don't say i didn't tell you 🙈

---

🧚 The d and dt Functions 🧚

as an alternative, DateTimeX::Auto can export a function called d. this might be useful if you'd prefer not to have every single string constant in your code turned into a DateTime (valid, honestly).

use DateTimeX::Auto 'd';
my $dt = d('2000-01-01');

• if d is called with a string that's in an unrecognised format, it croaks 💀
• if called with no arguments, it returns a DateTime representing the current time ⏰

an alias dt is also available. they're exactly the same. no difference. twins. 👯

---

🌈 The dur Function 🌈

called with an ISO 8601 duration string, it returns a DateTimeX::Auto::Duration object. cute, short, does the thing ✨

---

💅 Object-Oriented Interface 💅

okay so this somewhat negates the whole purpose of the module 😭 but you can also use it without exporting anything, in the usual normal Perl object-oriented fashion:

use DateTimeX::Auto;

my $dt1 = DateTimeX::Auto::DateTime->new('2000-01-01T12:00:00.1234');

# Traditional DateTime style
my $dt2 = DateTimeX::Auto::DateTime->new(
  year  => 2000,
  month => 2,
  day   => 3,
);

here's how it behaves, and pay attention bestie 📝:

• called in the traditional DateTime style, it throws an exception if the date isn't valid 🚨
• called in the DateTimeX::Auto::DateTime stringy style, it returns undef if the date isn't in a recognised format, but throws if it's otherwise invalid (e.g. the 30th of February — girl, that doesn't exist 💀)

there is similarly a DateTimeX::Auto::Duration class, which is a similar thin wrapper around DateTime::Duration 🎀

---

🌸 EXAMPLES 🌸

use DateTimeX::Auto ':auto';

my $date = '2000-01-01';
while ($date < '2000-02-01')
{
  print "$date\n";
  $date += 'P1D'; # add one day
}

use DateTimeX::Auto 'd';

my $date = d('2000-01-01');
while ($date < d('2000-02-01'))
{
  print "$date\n";
  $date += dur('P1D'); # add one day
}

look at that loop just working. ate and left no crumbs 🔥

---

👀 SEE ALSO 👀

DateTime, DateTime::Duration, DateTimeX::Easy — go read those too bestie, they're the supporting cast 💜

---

✨ AUTHOR ✨

Toby Inkster <tobyink@cpan.org> 🫶

---

🎀 COPYRIGHT 🎀

Copyright 2011-2012, 2014 Toby Inkster

This library is free software; you can redistribute it and/or modify it under the same terms as Perl 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.

(that's the legal girlies talking, not me — but like, they mean it 😭)

---

and that's the whole page bestie!! this came to you from perl v5.36.0, dated 2022-11-20, and yes it's still DateTimeX::Auto(3pm) 💖 go forth and never call a constructor again. slay 💅✨🦋